Easy API MCP

Easy API MCP Skill

This skill teaches AI agents how to connect to and use the open-wa MCP integration hosted through Easy API.

What is this?

open-wa exposes a hosted MCP endpoint that wraps every Easy API method as a discoverable MCP tool. This is the recommended surface for AI agent integration.

Connection

The MCP endpoint uses Streamable HTTP transport — a single endpoint handles all operations:

• POST /mcp — JSON-RPC messages (initialize, tools/list, tools/call)
• GET /mcp — Server-initiated SSE stream when needed
• DELETE /mcp — Session termination

Authentication

Every request must include your Easy API key. Without it, you get 401 Unauthorized.

Methods to provide the key:

• Header: X-API-Key: YOUR_API_KEY

Client Configuration

Claude Desktop (claude_desktop_config.json):

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

Cursor / Windsurf: Add MCP server with URL http://localhost:8080/mcp and set X-API-Key header. Note: Cursor currently calls Streamable HTTP by the name "SSE" in its UI dropdown.

When to use hosted MCP vs alternatives

Tool Discovery

Tools are namespaced:

• messages.sendText — Send a text message
• chats.getAll — Get all chats
• groups.create — Create a group

Use tools/list (MCP protocol) to discover all available tools.

For debugging, visit /meta/mcp-tools.json on the API host.

Important Boundaries

• MCP is Easy API-only. Not available through createClient().
• MCP requires an apiKey. No key = server refuses to start.
• Auth is enforced on every request, not just initialization.
• Tool execution blocks until the WhatsApp session is fully connected.
• MCP exposes the same methods as HTTP API — no MCP-exclusive features.

Troubleshooting

401 Unauthorized

Your API key is missing or wrong. Verify:

1. Server has apiKey in config.json
2. Your client sends X-API-Key header with the correct value
3. mcp.enabled is true

Server refuses to start

MCP requires Easy API apiKey. Refusing to start with MCP enabled and no apiKey configured.

Set apiKey in your config before enabling MCP.

Tools list is empty

The schema registry has no methods registered. The open-wa runtime may not have fully initialized.

Tool execution returns "Session is not connected"

The WhatsApp session isn't ready yet. Wait for the session to be fully connected before calling tools.