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 MCP

• 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 agent

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)

The agent still needs your MCP client, prompt, and permissions model to decide when those tools should be called.

MCP vs direct HTTP API

Quick start

The source-backed v5 alpha path is to enable MCP in config and start Easy API with an API key. In the current source, this 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 --config ./wa.config.mjs

The configured MCP path is:

http://localhost:8080/mcp

The current packages/wa-automate/src/cli-runtime.ts source does not parse --mcp. Use the config file above; the config path is the current source-backed option.

Expected enabled state

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 illustrative local verification guidance, not captured output from this docs update. If mcpEnabled is false, the config was not loaded or mcp.enabled is not set. If mcpAvailable is false, confirm apiKey is configured. These health fields come from config and API key state; with the current source, enabled MCP is mounted 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 transport

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 a real MCP client and call tools/list. A healthy endpoint should list open-wa tools with names derived from the Easy API method catalog. Do not treat a raw curl JSON-RPC request or /meta/mcp-tools.json as a full MCP client handshake; the Streamable HTTP transport expects the standard client flow.

Configure AI clients

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 model

API Key Enforcement

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 access

The adapter exposes all Easy API methods as tools. An authenticated AI agent may be able to:

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

Permission scopes

There are no permission scopes in the current implementation. Any authenticated agent can call any exposed tool. 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 controlled

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 actions

When using MCP, monitor what the AI agent does 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 discovery

How tools are generated

The adapter generates tools from the schema registry. Each Easy API method becomes an MCP tool with:

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

List available tools

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 API

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 page

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 reference

In your wa.config.mjs:

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

Fields

• 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)

Troubleshooting

Without MCP: HTTP alternative

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 docs

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.

Related

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

Was this helpful?

Wally and his cute companion coffee mug are coding day and night to keep this up-to-date!

YesNo