# Easy API MCP

> Teaches AI agents how to connect to the open-wa hosted MCP surface via Easy API.

- Skill: `open-wa/easy-api-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add open-wa/easy-api-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/open-wa/easy-api-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: open-wa (https://skillmd.com/u/open-wa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/open-wa/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`):
```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

| Scenario | Use |
| :--- | :--- |
| AI agent interacting with WhatsApp | **Hosted MCP** (this) |
| Local CLI tool or IDE integration | **Hosted MCP** via Streamable HTTP |
| Custom SDK integration in your own app | `createClient()` directly (no MCP) |

## 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.