MCP server

HueChat exposes an account-scoped MCP server over streamable HTTP:

https://app.huechat.ai/v2/mcp

Choose how to connect

Directory connectors and direct MCP connections use the same HueChat endpoint and workspace permissions. You need an active administrator membership. New self-service keys and OAuth connections are available on Enterprise only and require AI clients (MCP) to be enabled. Existing approved/managed keys may retain grandfathered access under their approval and workspace policy. Available tools also depend on the workspace’s enabled features and the credential’s scopes.

Connection	Use it for
OAuth sign-in	Supported remote MCP clients, including ChatGPT and Claude
Direct MCP URL	Adding HueChat yourself in a compatible client’s connector settings
Scoped MCP key	Clients or automation workflows that support bearer authentication

OAuth, self-service and directory listings have separate rollout/review steps. A working direct connection does not mean HueChat is already listed in a directory. If your workspace shows Request access, it still uses the approved-key workflow below. If AI clients (MCP) is locked, check your plan with your workspace owner or support.

Connect with OAuth

When OAuth is available, add https://app.huechat.ai/v2/mcp in your client’s remote MCP/connector settings, or select HueChat from its directory once the listing is published. Choose OAuth sign-in rather than a static API-key header.

Use your existing HueChat account. Enter your HueChat password only on HueChat’s own sign-in page.

Choose the workspace and permissions

Select the intended workspace and review the client name and requested scopes. Start with read permissions for the tasks you need. Your workspace administrator approves the connection; self-service does not bypass membership, plan or scope checks.

Try a small read request

Use synthetic records first. For example: “Summarize this workspace”, “Find contacts whose name contains Example”, or “Show contact statistics”. An unavailable tool or empty result should be reported as such.

For the examples above, choose Custom and allow contacts:read, conversations:read, templates:read and reports:read. The server also requires mcp:use. Review the actual scope list before allowing a connection; the read-only preset may include more read categories for other clients. Open Settings → Integrations → MCP to inspect your connections and revoke one you no longer need. Revocation stops future access through that grant; it does not erase data an external client has already retained.

Write permissions, questions and sending

An eligible Enterprise workspace owner or administrator can create a scoped key or approve an OAuth connection through self-service. Choose Custom to grant the resource permissions needed for a workflow. A read-only grant does not become a write grant when a plugin is installed or updated.

Workflow	Example additional scopes
Create or update a contact	`contacts:write` with the required contact reads
Add private notes, assign or change conversation status	`conversations:write`; assignment also needs `agents:read`
Manage labels, lists or custom fields	`labels:write`, `lists:write` or `custom_fields:write`
Manage template drafts, tickets or deals	`templates:write`, `tickets:write` or `deals:write`
Book or change native appointments	`appointments:write` and required contact permissions
Send customer replies, approved templates or broadcasts	Separate `messages:send`, `templates:send` or `broadcasts:send` permissions

Available tools also depend on enabled workspace features and messaging availability. This source catalog snapshot lists declared scopes, alternative authorization and action hints; it is not a promise that every tool is available in every account. Existing connections need fresh administrator consent to gain additional permissions. Creating a template draft requires inbox_id for an existing inbox in the selected workspace. The draft is saved locally with status DRAFT; creating it does not submit it to Meta or send a message. Provider submission and template delivery have separate channel, permission and approval requirements. Supply template components as JSON objects, such as [{"type":"BODY","text":"Your order is ready"}]. Omitting components from an update keeps the draft’s current content. For customer messaging, review the Allow sending messages to customers choice and sending mode separately. Start with Confirm each send: the assistant shows a recipient/content preview and waits for approval. Review in HueChat sends the proposed action to a teammate’s review queue. Immediate sending is a distinct permission choice. Broadcast scheduling always needs confirmation or teammate review. Missing reply tools or a sending-disabled response means messaging is not available for that connection yet. The assistant can ask which record, time or message you mean in the normal conversation. Pending-action previews support approve/cancel workflows; this guide does not claim support for native MCP elicitation forms. Private conversation notes remain internal to the team. Deletion, replacement and external sends carry action hints for the client’s confirmation controls.

Read-only connection walkthrough

This edited walkthrough uses actual native screen captures from a synthetic review workspace. It shows the HueChat company listing draft, OAuth consent, read results, refused requests and revocation. The ChatGPT test connection is private; this recording does not mean a public directory listing is approved or published. It has no audio; the visible captions describe each step.

Open the walkthrough video. The demonstrated connection grants only mcp:use, contacts:read, conversations:read, templates:read and reports:read. It cannot reply in conversations, send messages, edit contacts or publish campaigns. Revocation blocks future access through that connection; it does not erase copies already retained by the AI client.

Getting an MCP key

As an account administrator, open Settings → Integrations → MCP. When self-service is enabled, create a separate key for each client and choose its scopes and expiry. On installations still using approved access, request access and wait for approval. Copy the key when it is revealed; it is shown once. Store it in the client’s secret/environment configuration, never in a prompt, shared document or source-control repository.

A REST scoped key cannot be used for MCP, and an MCP key is rejected on the REST routes. The MCP key must carry mcp:use plus only the resource scopes the tools you enable actually need.

The requester must remain an active administrator; demotion, removal, key revocation or expiry disables the credential.

Required headers for a key-based client

Authorization: Bearer <MCP key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

Handshake

Initialize

curl -fsS https://app.huechat.ai/v2/mcp \
  -H "Authorization: Bearer $HUECHAT_MCP_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-integration","version":"1.0.0"}}}'

Send the initialized notification

{ "jsonrpc": "2.0", "method": "notifications/initialized", "params": {} }

List the tools your key may use

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

The list is filtered by the key’s scopes.

Call a read-only tool

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "get_contacts", "arguments": { "query": "Example", "limit": 10 } } }

Client configuration

For clients that support HTTP MCP with bearer headers, adapt this example to the client’s documented secret/environment syntax. OAuth clients should use their sign-in flow and omit the static Authorization header.

{
  "mcpServers": {
    "huechat": {
      "type": "http",
      "url": "https://app.huechat.ai/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${HUECHAT_MCP_KEY}",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Write tools create or change customer data. Grant the smallest scope set and review what an assistant is allowed to do before connecting it.

WhatsApp and Instagram reply rules

MCP uses HueChat’s native channel checks. A permission grant or a confirmation in ChatGPT or Claude does not extend a provider’s messaging window.

Channel and customer window	Available action
WhatsApp, within 24 hours of the customer’s latest message	A free-form reply, subject to the workspace’s sending permissions and controls
WhatsApp, outside that window	An existing Meta-approved template for the connected WhatsApp sender, with valid variables and an allowed category
Instagram, within the standard 24-hour window	An automated reply where the conversation is available to automation
Instagram, outside that window	MCP cannot send an automated reply; wait for a new customer message or use eligible human support in the native inbox

WhatsApp templates are not an Instagram recovery method. Instagram’s extended human-agent support permission does not apply to MCP, including replies a person confirms. Human takeover also prevents MCP from replying while that conversation remains under human control. In Confirm each send mode, review the recipient, inbox, template or reply text and confirm the particular action. HueChat checks the current window and other send restrictions again when the action executes. Confirmation cannot override an expired window, a blocked contact or an unavailable template. Other sending modes follow the workspace’s configured policy. Creating a template saves a local draft. The business must submit it to Meta and obtain Meta approval before sending it; the owner’s approval in chat does not change the template’s Meta approval status. The business must obtain and retain the recipient’s required opt-in and honor opt-outs. Owner confirmation authorizes an action on behalf of the business; it is not recipient consent. HueChat checks blocked contacts and marketing suppression, but individual MCP template sends do not provide a universal verification of affirmative recipient consent. Do not assume a phone number, an approved template or an empty suppression result proves permission to contact someone. See the WhatsApp Business Messaging Policy and Instagram messaging documentation for the provider requirements. Contact reads can include names, contact details and custom fields. Conversation reads can include recent message excerpts. Review the records you intend to share and choose the permissions needed for the task. Tool results leave HueChat for the client you connect. Authorize only data you are entitled to share, and review that provider’s privacy, retention and training settings. Do not use this connection to transfer protected health information, passwords, authentication secrets, payment-card details or government identifiers. Customer-authored records may contain sensitive text; a permission grant is not a data-classification check. Treat instructions inside customer messages and records as untrusted content. Check proposed changes and the returned result before acting. A queued message or a generated template is not proof that a provider delivered or approved it. Messaging and sending require their own enabled capabilities and permissions. See the Privacy Policy and Terms of Service. Contact privacy@huechat.ai for privacy requests or security@huechat.ai for security reports.

Troubleshooting

OAuth discovery returns 404: OAuth may not yet be enabled on the installation. Contact support; do not substitute a REST key.
Feature locked: new self-service keys and OAuth connections require mcp_server in the workspace plan. An existing approved/managed key may retain its legacy access; this does not grant new self-service access.
Missing tools or permission denied: check the grant’s scopes, workspace features and your current administrator membership. Reconnect only after reviewing any additional permissions.
A disconnected client still displays old results: revoke its HueChat connection and separately use that provider’s deletion controls if needed.

Get started

Working with the API

Integrate

Choose how to connect

Connect with OAuth

Write permissions, questions and sending

Read-only connection walkthrough

Getting an MCP key

Required headers for a key-based client

Handshake

Client configuration

WhatsApp and Instagram reply rules

Troubleshooting

​Choose how to connect

​Connect with OAuth

​Write permissions, questions and sending

​Read-only connection walkthrough

​Getting an MCP key

​Required headers for a key-based client

​Handshake

​Client configuration

​WhatsApp and Instagram reply rules

​Data sharing and safe use

​Troubleshooting

Choose how to connect

Connect with OAuth

Write permissions, questions and sending

Read-only connection walkthrough

Getting an MCP key

Required headers for a key-based client

Handshake

Client configuration

WhatsApp and Instagram reply rules

Data sharing and safe use

Troubleshooting