MCP integration

Use the Model Context Protocol (MCP) integration only when you want an authenticated AI agent to call Easy API tools. Treat the MCP endpoint like API access to your WhatsApp session.

Security checklist before you enable MCPCopy Anchor Link

• Start Easy API with apiKey. Source validation refuses MCP configuration without one.
• Send that key on every MCP request with X-API-Key, api_key, or key headers.
• Share the MCP URL only with clients you trust to read and send WhatsApp messages.
• Put the MCP endpoint behind HTTPS or a trusted reverse proxy before remote use.
• Use a dedicated WhatsApp session for AI-agent experiments.
• Watch logs and the MCP dashboard while testing new prompts or tools.

What MCP gives the agentCopy Anchor Link

The Model Context Protocol is a standard for connecting AI assistants to external tools and data sources. When enabled in config, open-wa mounts the MCP adapter and an authenticated AI agent can call Easy API methods as tools, including methods that can:

• Read incoming messages
• Send messages to any contact or group
• Access contact information
• Manage groups
• Send media (images, files, locations)

Your MCP client, prompt, and permissions model control when the agent can call these tools.

MCP vs direct HTTP APICopy Anchor Link

Quick startCopy Anchor Link

Enable MCP in config, then start Easy API with an API key. The runtime mounts the MCP adapter at the configured path.

Create wa.config.mjs:

export default {
  apiKey: process.env.WA_API_KEY,
  port: 8080,
  mcp: {
    enabled: true,
    path: '/mcp',
    exposeToolsMeta: true,
  },
};

Start Easy API from the same directory:

WA_API_KEY="your-secure-key" npx @open-wa/wa-automate@5.1.0 --config ./wa.config.mjs --session-id mcp --host 127.0.0.1 --port 8080

The configured MCP path is:

http://localhost:8080/mcp

If you set mcp.path to another value, use that path in the MCP client URL. The dashboard is served separately at /dashboard/mcp when the dashboard is enabled.

Enable MCP in the configuration file; the CLI does not have a --mcp flag.

Expected enabled stateCopy Anchor Link

After startup, check /health:

curl -s http://localhost:8080/health | jq '.capabilities.mcpEnabled, .capabilities.mcpAvailable, .capabilities.mcpPath'

Expected local result after config is loaded and an API key is present, illustrative local verification guidance:

true
true
"/mcp"

This output is an example, not captured output. If mcpEnabled is false, the runtime did not load the config or mcp.enabled is not set. If mcpAvailable is false, make sure that apiKey is configured. The health fields show the config and API key state. The source mounts enabled MCP during API route registration.

When tool metadata is enabled, you can also inspect the generated tool catalog:

curl -s http://localhost:8080/meta/mcp-tools.json | jq '.endpoint, .requiresApiKey, (.tools | length)'

Expected local result, illustrative local verification guidance:

"/mcp"
true
<number greater than 0>

If the tool count is 0, confirm the session finished authentication and the schema registry loaded. Tool metadata is useful for inspecting what is exposed, but it is not a successful MCP client handshake.

Streamable HTTP transportCopy Anchor Link

The adapter uses the Streamable HTTP transport for MCP. This means:

• Single endpoint, no separate SSE or messages paths. Everything goes through the configured MCP path.
• Session readiness, tools block until the WhatsApp session is fully connected. An AI agent cannot send messages before the session is ready.
• Stateful connections, the server maintains MCP session state across requests.

For a protocol-level check, connect with an MCP client and call tools/list. A healthy endpoint lists open-wa tools from the Easy API method catalog. A raw curl JSON-RPC request or /meta/mcp-tools.json is not a complete MCP client handshake. The Streamable HTTP transport needs the standard client flow.

Configure AI clientsCopy Anchor Link

Use these client snippets after you start Easy API with mcp.enabled and an apiKey in config.

{
  "mcpServers": {
    "open-wa": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "X-API-Key": "your-secure-key"
      }
    }
  }
}

Security modelCopy Anchor Link

API Key EnforcementCopy Anchor Link

Every MCP request must include the same API key as the Easy API. The adapter accepts X-API-Key, api_key, or key headers and rejects requests without a valid key.

What data AI agents can accessCopy Anchor Link

The adapter projects every method in the HTTP method schema catalog into an MCP tool. An authenticated AI agent can call those registered tools, including methods that can:

• Read all messages in all chats
• Send messages to any contact or group
• Access contact information
• Manage groups (create, modify, delete)
• Send media

Permission scopesCopy Anchor Link

There are no per-tool permission scopes in the current implementation. Any authenticated agent can call any tool in that catalog. Plan your deployment accordingly:

• Use a dedicated session for AI agent use
• Do not share the MCP endpoint publicly
• Monitor AI agent activity through logs

What happens if access is not controlledCopy Anchor Link

If the MCP endpoint is exposed publicly, the API key is leaked, or untrusted agents are allowed to use the key:

• Those agents can control your WhatsApp session
• Messages can be read and sent by unauthorized parties
• Session information can be accessed

Always use the API key, keep it secret, and consider placing the endpoint behind a reverse proxy.

Audit AI-agent actionsCopy Anchor Link

When you use MCP, monitor the AI agent through:

• The dashboard MCP page (http://localhost:8080/dashboard/mcp), where available
• API access logs
• Your reverse proxy access logs
• The session event log

Tool discoveryCopy Anchor Link

How tools are generatedCopy Anchor Link

The adapter projects method definitions from the HTTP method schema registry. Each registered method becomes an MCP tool with:

• A name matching the API method
• A description from the schema
• Typed parameters

List available toolsCopy Anchor Link

Connect with a real MCP client and call tools/list to see all available tools. The response includes each tool's name, description, and parameter schema.

Same methods as the HTTP APICopy Anchor Link

The implemented MCP tools are generated from the same method catalog as the HTTP API. Use the HTTP API docs as the fallback if MCP handshake or tools/list is unavailable.

Dashboard MCP pageCopy Anchor Link

When available in your build, open http://localhost:8080/dashboard/mcp to see:

• Connection status, whether MCP is configured and healthy
• Configuration snippets, copy-paste configuration for Claude Desktop, Cursor, and Windsurf
• Tool details, list of generated tool metadata with descriptions

Configuration referenceCopy Anchor Link

In your wa.config.mjs:

export default {
  apiKey: "your-secure-key",
  mcp: {
    enabled: true,
    path: "/mcp",
    exposeToolsMeta: true,
  },
};

FieldsCopy Anchor Link

• mcp.enabled, enable or disable MCP configuration (default: false)
• mcp.path, the configured URL path for the MCP endpoint (default: "/mcp")
• mcp.exposeToolsMeta, whether to expose tool metadata in the dashboard (default: true)

The environment adapter accepts the complete MCP object as JSON through WA_MCP. It does not expose separate WA_MCP_ENABLED, WA_MCP_PATH, or --mcp adapters, so use the config file when you want readable nested fields:

WA_MCP='{"enabled":true,"path":"/mcp","exposeToolsMeta":true}'

TroubleshootingCopy Anchor Link

Without MCP: HTTP alternativeCopy Anchor Link

If you prefer not to use MCP, use the HTTP API docs and schemas directly:

• Interactive docs: http://localhost:8080/api-docs/
• OpenAPI schema: http://localhost:8080/meta/swagger.json
• Postman collection: http://localhost:8080/meta/postman.json

LLM-readable docsCopy Anchor Link

The docs site generates LLM-readable content at:

• /llms.txt, index of all docs pages in LLM-readable format
• /llms-full.txt, full docs content for LLM consumption
• /llms.mdx/docs/$, per-page MDX for LLMs

AI agents can use these endpoints to read the docs without browsing the site.

Agent discovery endpointsCopy Anchor Link

The docs site also exposes machine-readable discovery documents so agents and tools can find the API and skill surface programmatically:

• /.well-known/mcp/server-card.json is reserved for deployments that host MCP. The docs site does not host MCP and returns 404 for this path.
• /.well-known/agent-skills.index.json, index of published Agent Skills for the open-wa packages.
• /.well-known/api-catalog, catalog pointing at the OpenAPI/HTTP API descriptions.
• /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, OAuth discovery documents for clients that negotiate auth automatically.

These describe the docs/agent surface. To actually call WhatsApp methods, an agent still connects to a running Easy API instance with a valid API key as described above.

RelatedCopy Anchor Link

• AI agent patterns, architecture patterns for AI agents
• Easy API quick start, start the API
• Security & deployment, production security