Get started
MCP server
Operate WhatsApp from an AI agent: Claude Code, Cursor or your own agent calls Nodium through the Model Context Protocol, with your API key.
Nodium serves its own MCP server at https://nodium.io/api/v1/mcp. An agent connected to it reads everything (numbers, conversations, contacts, templates, broadcasts, clients), sends messages one person at a time and keeps contacts up to date — as tools, without writing an HTTP client. It is the API, nothing more: each tool calls the matching route with your key, so client isolation, quotas, rate limits and the request log apply exactly as they do to your code.
Connect an agent
# Claude Code — reads onlyclaude mcp add --transport http nodium https://nodium.io/api/v1/mcp \ --header "Authorization: Bearer $NODIUM_KEY"# Letting the agent send messages too (send_message is off without ?send=true)claude mcp add --transport http nodium-send "https://nodium.io/api/v1/mcp?send=true" \ --header "Authorization: Bearer $NODIUM_KEY"# Acting for one of your clients by default (the tools can still name another)claude mcp add --transport http nodium-crm-4187 https://nodium.io/api/v1/mcp \ --header "Authorization: Bearer $NODIUM_KEY" --header "Nodium-Tenant: crm-4187"// .cursor/mcp.json, or the "mcpServers" block of any MCP client{ "mcpServers": { "nodium": { "url": "https://nodium.io/api/v1/mcp", "headers": { "Authorization": "Bearer nod_…" } } }}- Sending is off by default.
send_messageis listed, and callable, only when the server URL ends with?send=true. An agent that reads inbound messages reads text written by anyone: without that opt-in, an instruction hidden in a message cannot make it send anything. - No mass or configuration writes. Broadcasts, templates, clients and connect links are not tools: an agent reads messages written by anyone, and an instruction slipped into one of them must never trigger a send to everyone or change your account. Those stay with the API, called by your code.
- Give the agent its own key. A key opens the whole published API of your account; to confine an agent, pin its key to one client (
POST /keyswithclientId): it can never leave that client, whatever it asks. Give it an expiry (expiresInDays) and revoke it when the agent is retired. - Keep the key out of prompts and repositories: put it in the environment of the agent, as above.
The tools
- Numbers:
list_channels,get_channel,diagnose_channel. - Conversations and messages:
list_conversations,get_conversation,list_messages,get_message,mark_read, andsend_messagewith?send=true. - Contacts:
list_contacts,get_contact,update_contact. - Templates and Flows:
list_templates,get_template,list_flows. - Broadcasts:
list_broadcasts,get_broadcast,preview_broadcast(who it would reach; sends nothing). - Clients:
list_clients,get_client. - Billing:
get_billing_summary.
Each tool takes the fields of its route — its schema and description are drawn from this reference — plus an optional tenant: the client to act on, by Nodium id or your externalId. Without it, the Nodium-Tenant header of the connection applies, then the key's default client. Reads are marked read-only for the agent; writes are not.
What the agent receives
- A success returns the content of
data, as JSON text. A refusal returnsisError: truewith the API's{ "error": { "code", "message", … } }: the agent branches oncodelike your code does (window_closed→ send a template;rate_limited→ wait). send_messageneeds your ownidempotencyKey(8 to 200 characters): the agent reuses it when it retries, never for a new message.- A long answer is cut at 100,000 characters with a note: ask for fewer items (
limit) or the next page (cursor).
Protocol
- Streamable HTTP, revisions
2025-06-18and2025-03-26:initialize,ping,tools/list,tools/call. POST only — no server stream, and no session (Mcp-Session-Idis never issued): every call carries the key. - Without a valid key:
401with a JSON-RPC error. A call from a web page (anOriginother than Nodium's) is refused: a key never lives in a browser. - 600 calls per minute per address on the endpoint, then the usual limits of each route (600 per minute per client, 6,000 per key).
Without an MCP client
curl -X POST "https://nodium.io/api/v1/mcp?send=true" \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: 2025-06-18" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "send_message", "arguments": { "channelId": "4c1d…", "to": "+33612345678", "type": "text", "text": "Your order has shipped.", "idempotencyKey": "order-4187-shipped", "tenant": "crm-4187" } } }'# → { "jsonrpc": "2.0", "id": 1,# "result": { "isError": false, "content": [{ "type": "text",# "text": "{\"conversationId\":\"…\",\"message\":{\"status\":\"sent\",…},\"duplicate\":false}" }] } }