Developer Tools / MCP

MCP Integration

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

Browse WhatsApp chats

List captured WhatsApp chats and groups and use the returned chat JID as the projectId for follow-up tools.

Search Messages

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

Save Documents

Create mobile-responsive single-page HTML notes and summaries based on WhatsApp messages.

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 CONSTRUCTION_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 CONSTRUCTION_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 CONSTRUCTION_MCP_TOKEN="paste_token_from_dashboard"
claude mcp add --transport http construction-whatsapp https://construction.whasupcrm.com/api/mcp \
  --header "Authorization: Bearer $CONSTRUCTION_MCP_TOKEN"
claude mcp list

Codex

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

Codex

export CONSTRUCTION_MCP_TOKEN="paste_token_from_dashboard"
codex mcp add construction-whatsapp --url https://construction.whasupcrm.com/api/mcp --bearer-token-env-var CONSTRUCTION_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": {
    "construction-whatsapp": {
      "url": "https://construction.whasupcrm.com/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": {
    "construction-whatsapp": {
      "type": "http",
      "url": "https://construction.whasupcrm.com/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": {
    "construction-whatsapp": {
      "serverUrl": "https://construction.whasupcrm.com/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": {
    "construction-whatsapp": {
      "command": "bun",
      "args": [
        "run",
        "mcp"
      ],
      "cwd": "/path/to/apps/construction",
      "env": {
        "CONSTRUCTION_MCP_TOKEN": "paste_token_from_dashboard"
      }
    }
  }
}

Tools

Tool	Description	Parameters
list_projects	Lists WhatsApp chats and groups captured by your WhatsApp workspace.	installationId
search_messages	Searches captured WhatsApp messages by chat (projectId), text, date range, sender, and media presence.	projectId, query, from, to, includeMediaOnly, limit
get_message_context	Fetches nearby messages before and after a specific WhatsApp message.	whatsappMessageId, before, after
save_document	Saves a self-contained, mobile-responsive single-page HTML document back into the workspace.	projectId, title, contentHtml, sourceWhatsappMessageIds, metadata
create_share_link	Creates or returns a public share link for a saved document.	documentId

Examples

Weekly summary

You: "What has been happening across my WhatsApp this week?"

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

Assistant: "Here is a summary of the conversations I found, with source messages. Want me to save it?"

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

Assistant: Builds a single-page responsive HTML report with inline CSS, uses save_document, then create_share_link.

Find shared links

You: "Find the links shared in my WhatsApp chats this week."

Assistant: Uses search_messages with a date filter, then get_message_context around the relevant message.

Assistant: "Here are the links I found, with their original messages and senders."

Security

MCP tokens are scoped to one WhatSync 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

CONSTRUCTION_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