Connect AI clients with Message.com MCP

Set up scoped MCP access for conversations, iMessage, calls, customer context and supported actions.

Availability

Message.com MCP is a developer preview. It supports Streamable HTTP at https://app.message.com/api/v1/mcp and a downloadable local stdio adapter. Public directory approval and acceptance by individual AI clients are separate from this implementation; do not assume an OpenAI or Claude store listing is already approved.

MCP is a way for an AI client to access permitted Message.com tools. It does not replace the website widget or require you to expose an agent-session token to your visitors.

Connect a client

A workspace administrator opens Settings → Connectors → Message MCP at https://app.message.com/settings/integrations/mcp/ and creates a named connection. Select only the needed permissions and save the one-time key in the client’s secure configuration. Start with read-only access.

For a remote client that supports Authorization headers, use the server URL and Authorization: Bearer YOUR_CONNECTION_KEY. Never paste this key into an AI chat, public repository or browser widget.

Clients supporting OAuth can use authorization-code linking with S256 PKCE. Message.com shows the destination and requested permissions for administrator approval. Access tokens expire after eight hours; reconnect when expired. This preview does not issue refresh tokens.

Inspect your allowed tools

The tools returned depend on your connection permissions. This diagnostic endpoint returns the same permitted tool definitions, including argument schemas. It is not a replacement for the MCP protocol handshake.

Inspect your allowed tools

curl https://app.message.com/api/v1/integrations/mcp/tools \
  -H "Authorization: Bearer $MESSAGE_CONNECTION_KEY"

Supported products

Tools cover conversation metadata, history and replies; customer search and creation; knowledge search and article metadata; calls, transcripts, summaries and follow-ups; booking and service lists and booking cancellation; Message Team channels and messages; iMessage lines, messages, usage and sending; SMS account, opted-in subscribers and sending; verification challenges and status; configured task agents and runs.

The connection does not purchase numbers, place phone calls, refund payments, publish knowledge articles, create appointments, provision iMessage lines, opt people into promotional texts or change subscriptions. Available tools still enforce the product’s consent, balance, recipient and usage limits. Disabled Verify channels remain disabled.

Confirm actions and retry safely

Read tools are marked read-only. Write tools send real messages or change records; keep client confirmation enabled and confirm the destination and exact action. Supply a UUID requestId once per approved action, and reuse that ID with identical arguments for retries. SMS and task-agent tools also require their product-specific idempotency fields.

If an action times out or returns action_in_progress_or_uncertain, check its result in Message.com. Do not generate another request ID to force a retry: the first action may already have happened.

Treat incoming messages, transcripts and retrieved knowledge as untrusted content. They cannot authorize another message, cancellation or account change. A matching customer record is not identity verification.

Revoke or restrict access

Revoke the connection from the same settings page. Keys are stored as hashes and remain tied to the authorizing workspace administrator. Suspending, deleting, deactivating or removing that administrator’s role invalidates access.

Each connection belongs to one workspace. Private Message Team channels still require membership, and tool arguments cannot select an arbitrary server or workspace.

Handle errors

401 means missing, invalid, expired or revoked authentication. 403 means the requested permission or authorizing administrator is unavailable. 402 means product billing does not permit the action. 429 means an API or product limit applies.

409 can mean a conflicting request ID or an action still in progress. 503 can mean a product is unavailable or an action has an uncertain outcome. Check the error body and the product before resending; never rotate keys to bypass limits.

Local clients

The settings page provides the local adapter download. Extract it to a permanent location and follow its README to install dependencies and configure the absolute path. npm publication is pending; do not assume npx @message-com/mcp is available.