WhatsApp MCP JSON-RPC 2.0 Endpoint for AI Agents

The WhatsApp MCP API implements the Model Context Protocol (MCP) — a standard that lets AI agents discover and invoke typed tools at runtime. Rather than hard-coding API calls, an MCP-compatible agent queries the server for its tool list, reads the input schemas, and calls any tool by name. This server exposes 7 WhatsApp tools over a single HTTP endpoint so that any MCP client — Claude Desktop, a custom orchestrator, or any JSON-RPC consumer — can send and receive WhatsApp messages programmatically.

Endpoint Details

Field	Value
URL	`POST http://127.0.0.1:8790/mcp`
Protocol	JSON-RPC 2.0
Default Protocol Version	`2024-11-05`
Content-Type	`application/json`
Session Header	`mcp-session-id` (optional in request, always returned in response)
Server Name	`whatsapp-mcp-api`
Server Version	`0.2.0`

The host and port can be overridden with the WHATSAPP_MCP_HOST and WHATSAPP_MCP_PORT environment variables, but the default is 127.0.0.1:8790. The endpoint is POST only — a GET /mcp request returns a 404 not-found response.

Supported MCP Methods

All requests are POST /mcp with a JSON-RPC 2.0 body. The server routes on the method field. There is no streaming or SSE support — every request receives a single synchronous JSON response.

Method	HTTP Status	Description
`initialize`	200	Handshake — returns server capabilities and protocol version
`notifications/initialized`	202	Acknowledge initialization complete (empty body)
`tools/list`	200	Returns the full list of available WhatsApp tools with their input schemas
`tools/call`	200	Invoke a specific tool by name, passing arguments as a JSON object
(unknown method)	200	Returns a JSON-RPC error with code `-32601` and message `Method not found: <method>`

Initialization Flow

Every MCP session begins with an initialize handshake. Send the request once, save the mcp-session-id from the response header, and reuse it for all subsequent calls in the session. Pass your client’s protocolVersion in the request — the server echoes it back verbatim. If protocolVersion is omitted, the server defaults to "2024-11-05".

// Request — POST http://127.0.0.1:8790/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {}
  }
}

// Response — HTTP 200
// Response header: mcp-session-id: 3f8a2c1e-...
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "whatsapp-mcp-api",
      "version": "0.2.0"
    }
  }
}

After receiving the initialize response, send a notifications/initialized acknowledgment. The server returns HTTP 202 with no body.

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "notifications/initialized",
  "params": {}
}

List Tools

Retrieve the full tool manifest at any time. The response includes each tool’s name, description, and inputSchema so the agent knows exactly what arguments to pass.

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/list",
  "params": {}
}

Call a Tool

Invoke any tool by passing its name and a matching arguments object. The example below sends a WhatsApp text message.

// Request
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "whatsapp_send_message",
    "arguments": {
      "phone_number": "15551234567",
      "message": "hello from agent"
    }
  }
}

// Response — HTTP 200
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"ok\": true,\n  \"to\": \"15551234567\",\n  \"chat_id\": \"15551234567@c.us\",\n  \"message_id\": \"true_15551234567@c.us_3EB0...\",\n  \"timestamp\": \"2024-11-05T14:32:00.000Z\"\n}"
      }
    ]
  }
}

Every tool response is wrapped in a content array where each item has type: "text" and a text field containing a pretty-printed JSON string (JSON.stringify(payload, null, 2)). Parse the text value to get the structured result object.

Unknown Method

Any method value other than the four listed above returns a JSON-RPC error at HTTP 200. The error code is always -32601.

// Request
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/unknown",
  "params": {}
}

// Response — HTTP 200
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32601,
    "message": "Method not found: tools/unknown"
  }
}

Session Header

The server tracks calls with a mcp-session-id header. It is returned on every response and can optionally be included in subsequent requests to maintain a named session.

If you omit mcp-session-id in a request, a new UUID is auto-generated for that response.
If you include mcp-session-id in a request, the same value is echoed back in the response header.

# First call — no session header sent
curl -s -D - -X POST http://127.0.0.1:8790/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' \
  | grep -i mcp-session-id
# mcp-session-id: 3f8a2c1e-...

# Subsequent calls — pass the received session ID
curl -s -X POST http://127.0.0.1:8790/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: 3f8a2c1e-..." \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

CORS

The server includes full CORS headers on every response, including preflight OPTIONS requests. Browser-based MCP clients and local dashboards can call the endpoint without any proxy configuration.

Header	Value
`access-control-allow-origin`	`*`
`access-control-allow-methods`	`GET,POST,OPTIONS`
`access-control-allow-headers`	`content-type,mcp-session-id`
`access-control-expose-headers`	`mcp-session-id`

The access-control-expose-headers entry is what allows browser clients to read the mcp-session-id from the response and pass it in future requests.

AI Agent Integration

Any MCP-compatible client or AI orchestrator can point to POST http://127.0.0.1:8790/mcp and immediately discover all 7 WhatsApp tools via tools/list. The workflow is:

Start the server — node server.js (runs on 127.0.0.1:8790 by default).
Authenticate WhatsApp — call whatsapp_start_auth or whatsapp_pairing_code to link a phone. The session is persisted in the .wwebjs_auth directory so subsequent restarts skip re-authentication.
Point your agent at the endpoint — configure the MCP client URL to http://127.0.0.1:8790/mcp.
Let the agent call tools — the agent can check status, list chats, read messages, and send messages all through standard MCP tools/call requests.

MCP Tool Reference

Full parameter and response documentation for all 7 WhatsApp tools.

REST API Overview

Explore the traditional REST endpoints for direct HTTP integration.

REST API

MCP Endpoint

WhatsApp MCP JSON-RPC 2.0 Endpoint for AI Agents

Endpoint Details

Supported MCP Methods

Initialization Flow

List Tools

Call a Tool

Unknown Method

Session Header

CORS

AI Agent Integration

MCP Tool Reference

REST API Overview

Build docs developers (and LLMs) love

REST API

MCP Endpoint

Documentation Index

​Endpoint Details

​Supported MCP Methods

​Initialization Flow

​List Tools

​Call a Tool

​Unknown Method

​Session Header

​CORS

​AI Agent Integration

MCP Tool Reference

REST API Overview

Build docs developers (and LLMs) love

Endpoint Details

Supported MCP Methods

Initialization Flow

List Tools

Call a Tool

Unknown Method

Session Header

CORS

AI Agent Integration