Developer Tools / MCP

MCP Integration

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

Browse Projects

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

Search Messages

Find site conversations by text, sender, time range, project, and media attachments.

Save Documents

Create mobile-responsive single-page HTML reports, daily logs, site notes, and summaries.

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 the construction workspace.	installationId
search_messages	Searches captured WhatsApp messages by project, 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 happened on the Downtown project this week?"

Assistant: Uses list_projects, 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: Builds a single-page responsive HTML report with inline CSS, uses save_document, 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 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