MCP server

The MCP server: its tools, settings and safety rules.

An MCP server that lets an MCP client (for example Claude Desktop or Claude Code) read one channel of the gateway's public API: the channel's status, the chats it has observed, recent messages in a chat, its groups and communities, and a contact. Sending (a text, media by URL, a poll, a reaction) is available only when you turn it on. It talks to the public API (or an API base URL you set) with your own channel token, over stdio, and makes no other network calls.

Install

Requires Node.js 22 or later. Run it with npx, no separate install step:

npx -y @wagate/mcp

Your MCP client starts the server for you once it is configured (see Claude Desktop and Claude Code below). The server reads its settings from the environment variables listed under Environment.

Tools

Not exposed, on purpose: group and community invite links (an agent could paste an open invite into a chat), media download (bytes, not JSON) and webhook configuration.

get_group returns the group's participant list, which is your own group data, so it enters the MCP client's context like any other tool result. Use it only with a client you trust with those member identities.

The public API forwards only limit (1 to 500) and before on the conversation read, so read_messages pages with those two and no other query string reaches the API. The other list tools take no paging parameters.

A chat is sent in the URL path without percent-encoding, because the API refuses any path containing %. A chat containing anything other than letters, digits and @ . : _ + - is refused before a request is made.

Every request sends Authorization: Bearer <token>. A successful response is returned as JSON text. An HTTP error is returned as a tool error with status, code and error, plus retry_after (and window, resets_at, ambiguous, id) when the API sends them. The token is redacted from every string returned, success bodies included. Nothing is retried automatically, and a redirect is refused rather than followed.

Environment

If a required variable is missing the server writes the reason to stderr and exits with status 1.

Sending is off by default

Without GATEWAY_ALLOW_SEND=1 no send tool is registered: a client cannot see or call them, and the server never contacts a send endpoint. With it on, every call sends a real WhatsApp message from the linked number (a reaction, its removal and a delete included) and counts as one against the channel's daily send cap if it has one (an operator can exempt a channel from the cap).

A send can succeed without saying so

A failed send_text carries delivery: "unknown" when the message may have been sent anyway: no response arrived, the API answered ambiguous: true (a 504 send_unconfirmed, with the id of the row it logged), or the answer was any other 502 or 504. Do not send it again. Check read_messages for that chat first. Sending it again is how the same message reaches a real person twice.

Prompt injection: read and send together let strangers steer sends

read_messages puts text written by third parties, anyone who can message the number, into the model's context. With GATEWAY_ALLOW_SEND=1 in the same server, that text can instruct the model to send messages, to anyone, with any content. This is not solved by trusting the client or the person using it: the instructions come from the messages being read.

Run reading and sending as two separate client configurations:

• a read-only entry, without GATEWAY_ALLOW_SEND, for anything that reads messages;
• a send entry, with GATEWAY_ALLOW_SEND=1, enabled only in a session that needs to send, with every send_text call approved by a person who reads its to and text.

The send entry still registers the read tools, so a session using it is exposed the moment it reads messages. Keep that session away from read_messages unless you trust everyone who can message the number.

Claude Desktop

Add an entry to mcpServers in claude_desktop_config.json:

{
  "mcpServers": {
    "wagate-mcp": {
      "command": "npx",
      "args": ["-y", "@wagate/mcp"],
      "env": {
        "GATEWAY_API_TOKEN": "<CHANNEL_TOKEN>",
        "GATEWAY_CHANNEL_ID": "<CHANNEL_ID>"
      }
    }
  }
}

Add "GATEWAY_ALLOW_SEND": "1" to env to enable sending. Restart Claude Desktop after editing the file.

Claude Code

claude mcp add wagate-mcp \
  -e GATEWAY_API_TOKEN=<CHANNEL_TOKEN> \
  -e GATEWAY_CHANNEL_ID=<CHANNEL_ID> \
  -- npx -y @wagate/mcp

Add -e GATEWAY_ALLOW_SEND=1 before -- to enable sending.

Both clients store the token in their configuration file in plain text. Use the channel's own token, never an operator credential.

Example requests

Once connected, ask your assistant in plain language. For example:

• "What is the status of my channel?" (calls channel_status)
• "Show the last 20 messages in my chat with [email protected]." (calls read_messages)
• "List the groups this number is in." (calls list_groups)

License

MIT.