ChatArchitect Cloud MCP Server for WhatsApp AI Agents

AI agents need tools, not just chat

AI agents can classify requests, draft replies, summarize conversations, and choose the next step in a workflow. To carry out that step, they need access to business tools. An agent that can draft a reply also needs a messaging tool to deliver it.

For many businesses, WhatsApp is that channel. Sales teams use it to follow up with leads, support teams use it to respond to customer questions, and operations teams use it to send appointment, delivery, payment, and status notifications. The value of AI grows when the agent can move from suggestion to controlled execution: send a text message, create or list a template, request billing information, check failed messages, export data, or configure workflow endpoints.

ChatArchitect Cloud MCP Server is designed for exactly this layer. It gives AI clients a controlled way to call selected ChatArchitect WhatsApp API actions through the Model Context Protocol, without asking each client to build and maintain a custom backend integration.

What is MCP in simple words?

MCP, or Model Context Protocol, is a standard way for AI applications to connect to external tools. In an MCP setup, the AI application acts as a client. The MCP server exposes a set of available actions, their input schemas, and their output formats. The AI client can discover those actions and call them when the user gives a task that requires real execution.

Think of MCP as a standard adapter between an AI agent and a business system. Security depends on the server's authentication and validation, the client's permissions, and how the connection is operated. The agent does not need to know the internal API details of every service. It sees a stable list of tools with clear names and parameters. The server handles authentication, validation, upstream API calls, response normalization, and error mapping.

That separation is important. It means the AI client can work with a business capability, such as send_whatsapp_text_message, instead of learning the full raw ChatArchitect API. It also means the business can keep secrets, internal parameters, and operational rules out of model-facing tool arguments.

What is ChatArchitect Cloud MCP Server?

ChatArchitect Cloud MCP Server is a public remote MCP facade for the ChatArchitect WhatsApp API. It is implemented as a Node.js and TypeScript service using Express, createMcpExpressApp() from @modelcontextprotocol/express, and NodeStreamableHTTPServerTransport from @modelcontextprotocol/node.

The server exposes one public MCP transport entrypoint: POST /mcp. AI clients connect to that endpoint, authenticate with a Bearer token, discover the supported tools, and call the actions enabled by their client configuration. A valid account token gives access to the server's tool surface; per-tool restrictions and approval policies must be configured in the AI client.

This is a focused v1 facade, not a full mirror of every ChatArchitect API capability. The current implementation intentionally keeps the public tool surface narrow. It exposes 10 MCP tools for WhatsApp messaging, payment links, notifications, templates, exports, failed messages, webhooks, and billing. It does not expose MCP prompts or resources. It does not receive webhook delivery callbacks. It does not support SSE on GET /mcp; in v1, GET /mcp and DELETE /mcp deliberately return 405 Method Not Allowed.

The main benefit for clients is simple: they can connect an AI agent to WhatsApp and ChatArchitect workflows without designing their own MCP server, OAuth surface, token validation, request context handling, upstream client, tool schemas, and response normalization from scratch.

Why cloud MCP is useful for clients

ChatArchitect Cloud MCP Server provides a ready integration layer. Clients connect their AI tool to a cloud endpoint, authorize access, and start with a stable set of WhatsApp and ChatArchitect actions. Updates, internal upstream mappings, request validation, and the MCP transport are handled in one place.

A team can start with one support reply or internal notification, then expand into workflows with CRM, helpdesk, n8n, OpenAI Responses API, ChatGPT, AI IDE tooling, and custom backends. Validate each client's transport, authentication, and approval behavior before rollout.

What clients can do with it

For sales teams, ChatArchitect MCP can help an AI agent reply to a WhatsApp enquiry, prepare an offer, or notify a manager when a lead becomes urgent. A website form alone does not open WhatsApp's customer service window: business-initiated outreach outside the 24-hour window requires an approved message template.

For customer support, the connection can confirm that a request was received, send a status update within an open customer service window, or hand off context to another workflow.

For operations, the tools can connect billing checks, exports, internal notifications, and WhatsApp replies to CRM workflows. The current WhatsApp send tool is text-only. Creating or listing templates does not provide a tool for sending template messages; use a separately supported ChatArchitect flow where a template is required.

For developers and automation teams, the value is a stable protocol boundary. Instead of giving every AI workflow direct access to raw API credentials and raw ChatArchitect endpoints, developers can connect the AI layer to a curated MCP server. The server validates inputs with Zod schemas, injects internal upstream parameters, maps ChatArchitect responses into stable structuredContent, and returns predictable errors.

How it works

AI Agent / ChatGPT / OpenAI Responses API / n8n / VSCode / Custom Backend
        |
        v
ChatArchitect Cloud MCP Server
        |
        v
ChatArchitect WhatsApp API and business logic
        |
        v
Customer on WhatsApp

The flow is straightforward:

  1. An AI agent receives a task, such as sending a follow-up to a new lead.
  2. The AI client discovers the tools available from the ChatArchitect MCP server.
  3. The client calls a tool through POST /mcp with Authorization: Bearer <token>.
  4. The MCP server validates the token and extracts the ChatArchitect account credentials from the encrypted token body.
  5. The server validates the tool arguments and calls the required ChatArchitect upstream endpoint.
  6. The response is normalized into stable MCP structuredContent.
  7. The result returns to the AI client or automation workflow.

The AI client does not receive app_id or secret as tool parameters. Those credentials are handled at the authorization layer, not in prompts or model-facing schemas.

Authorization and security model

The public MCP endpoint accepts only Bearer authentication at the MCP request level. The token contract is nested: an outer compact JWE contains an inner signed JWT. The access token is encrypted with dir and A256GCM, while the inner JWT is signed with HS256.

The token must contain the required claims used by the server: sub=chatarchitect-session, app_id, secret, exp, iss, and aud. The issuer must match PUBLIC_BASE_URL, and the audience must match ${PUBLIC_BASE_URL}/mcp. The optional fixed scope is mcp.

This design keeps ChatArchitect credentials out of model-facing tool inputs and normal tool responses. The authorization layer supplies them to the server, which uses internal Basic authentication when calling the upstream ChatArchitect API. Credentials remain sensitive: enter them only on the trusted authorization page and keep tokens out of prompts, shared configuration files, and screenshots.

The implementation also includes request timeouts, upstream timeouts, body size limits, host header protection through createMcpExpressApp() and optional ALLOWED_HOSTS, masked app IDs in child loggers, and redaction helpers for sensitive values.

For client-side control, write tools can be placed behind approval in the AI application. Read-only tools, such as billing lookup or template listing, can usually be allowed without approval, while write tools, such as sending a WhatsApp message or configuring webhooks, can require human confirmation.

Supported MCP tools

The external MCP contract is the tool layer. Tool names are fixed and should be treated as stable integration names.

ChatArchitect MCP tools and operation types
ToolTypeDescription
send_whatsapp_text_messageWriteSends a WhatsApp text message through ChatArchitect. It supports only the whatsapp channel and text-only payloads. Required inputs are channel, destination, and text; external_id is optional.
get_payment_urlPayment link creationCreates and returns a ChatArchitect payment URL for an email and integer amount. payment_type defaults to card; supported values are card and wire. For accounts billed in EUR, the minimum is 30 € for either payment method. Creating the link does not execute a payment.
send_notificationWriteSends a ChatArchitect notification with name, source, and text. The normalized output confirms that the notification was sent.
create_templateWriteCreates a text-only ChatArchitect template. Inputs include slug-safe element_name, language_code, category, content, optional example, and required vertical. The upstream call uses templateType: "TEXT".
export_chatarchitect_dataRead-onlyExports ChatArchitect CSV data. Supported actions are phones, sent, received, and conversations. Supported ranges are last_month, this_month, yesterday, and today. page must be at least 1.
list_templatesRead-onlyLists ChatArchitect templates for a WhatsApp destination. Inputs are channel=whatsapp and destination. Output is a stable array of template names, statuses, and optional language codes.
get_last_failed_messagesRead-onlyReturns the latest failed messages for a WhatsApp destination. Inputs are channel=whatsapp and destination.
set_webhooksWriteConfigures ChatArchitect webhook URLs. The public inputs include optional webhook, webhook_separate, webhook_message_event, and webhook_user_event. Webhook URLs must use https://.
get_webhooksRead-onlyReads the current ChatArchitect webhook configuration. If the upstream backend does not support GET /webhook and returns 404 or 405, the MCP server maps that to unsupported_by_backend.
get_billingRead-onlyReturns the billing summary with clients_max, due_date, clients_active, balance, and billing_status (active or expired). This is a synthetic tool implemented through an internal ChatArchitect request flow.

The read-oriented tools are export_chatarchitect_data, list_templates, get_last_failed_messages, get_webhooks, and get_billing. The tools that change state or create an object are send_whatsapp_text_message, send_notification, create_template, set_webhooks, and get_payment_url.

These labels describe the operations; they are not server-enforced per-tool permissions or MCP safety annotations. Configure allowed tools and approvals by tool name in your AI client. A conservative pilot requires confirmation before sending a message, changing webhooks, creating a template, or generating a payment link.

Example scenario: replying to a WhatsApp enquiry

A customer messages your business on WhatsApp to ask about a demo. The incoming message and CRM context are passed to an AI workflow. Within 24 hours of that customer's most recent message, the agent prepares a reply confirming the enquiry and offering a demo time.

The client can ask:

Draft a reply to this WhatsApp enquiry and offer a demo call tomorrow. Ask me to approve the final text before sending it.

The AI client sees that ChatArchitect MCP provides send_whatsapp_text_message. If the tool is allowed and approval rules are satisfied, the client calls the MCP server. The server validates the Bearer token, checks that the tool input contains only the supported WhatsApp text fields, sends the message through ChatArchitect, and returns the normalized result.

Keep approval in the client and record the tool result in your workflow. For business-initiated messaging, obtain the required opt-in. Outside the 24-hour customer service window, use an approved template through a supported template-sending flow rather than this text-only tool. See the WhatsApp Business Messaging Policy.

Supported connection options

ChatArchitect Cloud MCP can be used from different AI and automation environments. The exact UI depends on the client, but the important rule is the same everywhere: use the full MCP endpoint URL, including /mcp.

https://api-mcp.chatarchitect.com/mcp

If a client is configured with only the base domain, it may send MCP requests to / instead of /mcp, and the tools will not appear.

ChatGPT Web

Where your ChatGPT plan and workspace permit custom MCP integrations, add ChatArchitect as a custom MCP plugin. Workspace administrators may need to enable or approve access.

Example setup:

  1. Open ChatGPT's Plugins area.
  2. Select +, then Add custom MCP server.
  3. Enter this server URL and choose OAuth authentication:
https://api-mcp.chatarchitect.com/mcp
  1. Create the plugin, install it, and complete the authorization flow.
  2. Enter your ChatArchitect app_id and secret only on the trusted authorization page.
  3. Enable the tools needed for your scenario and test a read-oriented action first.

Interface labels and availability can change; use the official ChatGPT MCP connection instructions for your account.

Example prompt after connection:

Use the ChatArchitect plugin to list WhatsApp templates for this destination.
Do not send a message unless I confirm the final text.

Configure tool permissions and review write actions explicitly. A prompt asking for confirmation is useful, but does not replace the client's approval settings.

n8n

n8n can use MCP tools inside automation workflows. Use the MCP Client node when you want an MCP call as a regular workflow step. Use the MCP Client Tool node when your n8n AI Agent should be able to call external MCP tools.

Recommended setup for this server:

  1. Add an MCP Client node, or an MCP Client Tool node if your n8n version supports Streamable HTTP for that node.
  2. Set the MCP endpoint URL to:
https://api-mcp.chatarchitect.com/mcp
  1. Select Bearer or OAuth2 authentication.
  2. For Bearer authentication, provide a short-lived ChatArchitect MCP access token:
Authorization: Bearer <chatarchitect-mcp-token>
  1. For OAuth2 authentication, use the server metadata and endpoints exposed by ChatArchitect MCP:
Authorization server metadata:
https://api-mcp.chatarchitect.com/.well-known/oauth-authorization-server

Protected resource metadata:
https://api-mcp.chatarchitect.com/.well-known/oauth-protected-resource
  1. Choose the tool to call, or expose selected tools to an AI Agent.

Example n8n workflow:

Incoming WhatsApp Message
  -> Check the 24-hour customer service window
  -> AI Agent drafts a reply
  -> Human approval
  -> MCP Client Tool: send_whatsapp_text_message
  -> CRM Update

Check the n8n MCP Client Tool documentation and the transport capabilities of your installed version.

ChatArchitect MCP v1 does not implement SSE on GET /mcp; GET /mcp returns 405. If an n8n node or older n8n installation only accepts an SSE endpoint, use a Streamable HTTP-capable MCP node or place a compatible adapter in front of the MCP server.

Claude Code

Claude Code supports remote HTTP MCP servers. This makes it useful for technical teams that want to inspect or test ChatArchitect workflows while working in a repository.

OAuth-based setup:

claude mcp add --transport http chatarchitect https://api-mcp.chatarchitect.com/mcp

Then, inside Claude Code, run:

/mcp

Claude Code opens the OAuth flow for remote servers that require authentication. After the flow is completed, the ChatArchitect tools become available in the Claude Code session.

If your backend mints a short-lived Bearer token and you want to pass it directly, use a header-based configuration:

claude mcp add --transport http chatarchitect https://api-mcp.chatarchitect.com/mcp \
  --header "Authorization: Bearer <chatarchitect-mcp-token>"

For a team-shared project configuration, Claude Code can also store MCP servers in a project .mcp.json file. Keep credentials out of shared files; follow the Claude Code MCP documentation for authentication and permissions:

{
  "mcpServers": {
    "chatarchitect": {
      "type": "http",
      "url": "https://api-mcp.chatarchitect.com/mcp"
    }
  }
}

Example Claude Code prompt:

Use the ChatArchitect MCP server to check billing and list the last failed WhatsApp messages.
Do not call write tools.

Codex

Codex can connect to remote MCP servers from the CLI or IDE extension. This is useful when developers want Codex to inspect ChatArchitect MCP tools, test tool contracts, or help build workflows that call ChatArchitect actions.

CLI setup:

codex mcp add chatarchitect --url https://api-mcp.chatarchitect.com/mcp
codex mcp login chatarchitect
codex mcp list

Equivalent direct configuration in ~/.codex/config.toml:

[mcp_servers.chatarchitect]
url = "https://api-mcp.chatarchitect.com/mcp"

Run codex mcp login chatarchitect to start OAuth and enter your ChatArchitect credentials on the trusted authorization page.

For a backend-minted Bearer token, use an environment variable rather than a literal token in the configuration:

[mcp_servers.chatarchitect]
url = "https://api-mcp.chatarchitect.com/mcp"
bearer_token_env_var = "CHATARCHITECT_MCP_TOKEN"

Set CHATARCHITECT_MCP_TOKEN securely in the environment before starting Codex. Use either OAuth or the Bearer-token configuration for the connection. See the Codex MCP documentation for tool controls and authentication options.

Example Codex prompt:

Use the ChatArchitect MCP server to inspect the available tools.
Then draft a safe test plan for get_billing, list_templates, and send_whatsapp_text_message.
Do not send any WhatsApp message unless I explicitly approve the exact text.

Cursor

Cursor supports custom MCP servers through mcp.json. Use a project-level config when the connection should apply only to one repository, or a global config when you want the server available across projects.

Project-level file:

.cursor/mcp.json

Global file:

~/.cursor/mcp.json

OAuth-style remote server configuration:

{
  "mcpServers": {
    "chatarchitect": {
      "url": "https://api-mcp.chatarchitect.com/mcp"
    }
  }
}

Bearer-token configuration using an environment variable:

{
  "mcpServers": {
    "chatarchitect": {
      "url": "https://api-mcp.chatarchitect.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CHATARCHITECT_MCP_TOKEN}"
      }
    }
  }
}

Example Cursor prompt:

Use the ChatArchitect MCP tools to list templates for this WhatsApp destination.
If a message needs to be sent, draft it first and wait for approval.

Enable only the tools needed for the workflow and use client approval controls for actions that change state. See the Cursor MCP documentation for configuration and environment-variable handling.

When should you use ChatArchitect MCP?

Use ChatArchitect MCP when you already have, or plan to build, an AI workflow that needs to act in WhatsApp or ChatArchitect instead of only producing text. It is a good fit when you want an AI agent to send WhatsApp messages, work with templates, export conversation-related data, inspect failed messages, check billing, or connect WhatsApp actions into CRM and support workflows.

It is also useful when you want a controlled integration boundary. The AI client can be allowed to call only selected tools. Write operations can require approval. Tool schemas stay narrow. Secrets stay out of prompts and tool arguments. Upstream details remain inside the MCP server.

The cloud endpoint lets your team connect without deploying its own MCP infrastructure. You can focus on the workflow and the customer experience while ChatArchitect provides the execution layer.

What you need to start

To start with ChatArchitect Cloud MCP, you need a ChatArchitect account, an active WhatsApp Business API setup, access to the MCP endpoint, an authorization method for the MCP Bearer token or OAuth flow, and an AI client or automation tool that can call MCP. For a first pilot, choose one simple scenario: a lead follow-up, support confirmation, payment reminder, or internal notification.

From there, define which tools the AI client can use. A conservative setup usually allows read-only tools without approval and requires approval for write tools. For example, the client can read billing or list templates freely, but must ask a human before sending a WhatsApp message or changing webhook settings.

FAQ

Is this only for developers?

No. Developers can connect through OpenAI Responses API or a custom backend, but automation teams can also use MCP-capable no-code or low-code tools. The goal is to provide a standard tool interface that different AI clients can use.

Do I need to host my own MCP server?

No. ChatArchitect Cloud MCP Server is designed as a hosted MCP endpoint. Clients connect to the cloud endpoint instead of deploying and maintaining their own MCP server.

Can AI send WhatsApp messages automatically?

Yes, when the client has configured authorization, allowed tools, and approval rules. For sensitive workflows, write tools should require confirmation before execution.

Can I require approval before sending?

Yes. Configure approval rules in the AI client by tool name. The current server does not enforce those rules or publish per-tool safety annotations, so review the client's behavior rather than assuming automatic classification.

Can I disable or restrict access later?

You can disconnect the integration or disable tools in the client. This controls that client, but does not revoke already issued tokens. The current v1 server has no OAuth revocation endpoint; issued access tokens remain usable until expiry. Coordinate server-side access changes with ChatArchitect when access needs to stop.

Is it suitable for production?

The server includes Bearer authentication, encrypted access tokens, schema validation, timeouts, response normalization, and redaction helpers. These features do not establish readiness for every deployment. Before production rollout, validate representative workflows in a test account, confirm client approvals, monitor failures, and follow WhatsApp Business rules.

Start your MCP workflow

Want to connect your AI agent to WhatsApp? Contact ChatArchitect and we will help you set up Cloud MCP for your use case.

Already have an AI workflow? Send us your scenario and we will show how to connect it through MCP.

Discuss your MCP workflow