Developer Tools / MCP

MCP Integration

Connect AI tools to your CRM WhatsApp workspace. The hosted MCP endpoint is the default setup; local stdio is only needed when you are running the repo yourself.

Browse Conversations

List readable WhatsApp conversations across your own account or the team accounts your role can access.

Search Messages

Find customer conversations by text, sender, time range, chat, and media attachments.

Save Notes

Create issue notes, conversation summaries, follow-up lists, and other CRM records.

Create Share Links

Generate public links for saved documents when a stakeholder needs the output outside the dashboard.

Quickstart

1
Open the dashboard and connect WhatsApp from the WhatsApp Session card.
2
Pick the WhatsApp groups to track in Group Sync.
3
The examples use CRM_MCP_TOKEN for CLI setup and embed the same token in JSON configs.
4
Use the hosted Streamable HTTP endpoint unless the client only supports local stdio.

Token variable used by examples

export CRM_MCP_TOKEN="paste_token_from_dashboard"

Client Setup

Claude Code

Claude Code supports Streamable HTTP directly. Add the server URL first, then pass the authorization header.

Claude Code

export CRM_MCP_TOKEN="paste_token_from_dashboard"
claude mcp add --transport http crm https://whatan.app/api/mcp \
  --header "Authorization: Bearer $CRM_MCP_TOKEN"
claude mcp list

Codex

Codex uses `--url` for Streamable HTTP and reads the bearer token from an environment variable.

Codex

export CRM_MCP_TOKEN="paste_token_from_dashboard"
codex mcp add crm --url https://whatan.app/api/mcp --bearer-token-env-var CRM_MCP_TOKEN
codex mcp list

Cursor

Add this to `~/.cursor/mcp.json` or `.cursor/mcp.json`. Cursor resolves environment variables in `url` and `headers`.

Cursor mcp.json

{
  "mcpServers": {
    "crm": {
      "url": "https://whatan.app/api/mcp",
      "headers": {
        "Authorization": "Bearer paste_token_from_dashboard"
      }
    }
  }
}

VS Code Copilot

Add this to `.vscode/mcp.json` or your VS Code user MCP configuration.

VS Code mcp.json

{
  "servers": {
    "crm": {
      "type": "http",
      "url": "https://whatan.app/api/mcp",
      "headers": {
        "Authorization": "Bearer paste_token_from_dashboard"
      }
    }
  }
}

Windsurf

Add this to `~/.codeium/windsurf/mcp_config.json`. Windsurf uses `serverUrl` or `url` for remote HTTP MCP servers.

Windsurf mcp_config.json

{
  "mcpServers": {
    "crm": {
      "serverUrl": "https://whatan.app/api/mcp",
      "headers": {
        "Authorization": "Bearer paste_token_from_dashboard"
      }
    }
  }
}

Claude Desktop

Claude Desktop remote HTTP MCP servers are added through Settings > Connectors. Its JSON config is for local stdio servers, so use this only when running the repo locally.

Local stdio only

{
  "mcpServers": {
    "crm": {
      "command": "bun",
      "args": [
        "run",
        "mcp"
      ],
      "cwd": "/path/to/apps/crm",
      "env": {
        "CRM_MCP_TOKEN": "paste_token_from_dashboard"
      }
    }
  }
}

Tools

Tool	Description	Parameters
get_workspace	Returns the current workspace, member, token capabilities, and readable WhatsApp accounts.	installationId
list_conversations	Lists recent WhatsApp conversations across readable CRM accounts.	ownerMemberId, query, limit
search_messages	Searches captured WhatsApp messages by account, conversation, phone, text, date range, direction, and media presence.	ownerMemberId, conversationId, chatJid, phone, query, from, to, direction, includeMediaOnly, limit
get_conversation	Fetches one conversation and its recent messages using a conversation id.	conversationId, limit
get_message_context	Fetches nearby messages before and after a specific WhatsApp message.	whatsappMessageId, before, after
send_message	Queues a WhatsApp text, image, or document message from the token owner account.	to, type, text/image/document, idempotencyKey
save_note	Saves an AI-generated CRM note back into the workspace.	conversationId, chatJid, title, contentMarkdown, sourceWhatsappMessageIds, metadata
create_share_link	Creates or returns a public share link for a saved note.	noteId

Examples

Weekly summary

You: "What happened with the Downtown account this week?"

Assistant: Uses list_conversations, then search_messages with a date filter.

Assistant: "I found 47 messages across delivery delays, electrical rough-in scheduling, and a safety concern with photos. Want me to save this as a weekly report?"

You: "Yes, save it and share the link."

Assistant: Uses save_note, then create_share_link.

Issue investigation

You: "Find messages about the foundation wall crack."

Assistant: Uses search_messages with "crack" and "foundation", then get_message_context around the relevant message.

Assistant: "I found the thread and attached photos. I can draft an issue report with source message ids."

Security

MCP tokens are scoped to one CRM installation and only expose that installation's tracked WhatsApp groups.
Treat the token like an API key. Do not commit it to version control.
The optional `installationId` argument is a sanity check. If present, it must match the token.

Troubleshooting

CRM_MCP_TOKEN is missing

Copy the token from the dashboard MCP Setup card and export it before using CLI commands or JSON configs that reference it.

Invalid or expired token

Copy a fresh token from the dashboard. Tokens are tied to one installation.

Tools return empty results

Confirm WhatsApp is connected, groups are selected in Group Sync, and messages have synced since connection.

Claude Desktop remote HTTP does not connect

Use Claude Desktop Settings > Connectors for remote MCP. The desktop JSON config is for local stdio servers.

Official References

Claude Code MCP Claude remote connectors Cursor MCP VS Code MCP Windsurf MCP Codex MCP