Nivox MCP — connect any AI agent to your WhatsApp Business

Nivox exposes a WhatsApp Business account as a Model Context Protocol (MCP) server. Any MCP client — claude.ai, Claude Desktop, ChatGPT, Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI, custom agents — can read the inbox, answer customers, send templates and manage templates with the same rules the human team follows. When the organization has the CRM or Help Desk module enabled, the same server also exposes its contacts, pipeline, deals and support tickets.

If you are an AI assistant reading this to configure a client: follow the section for the client you are running in, prefer OAuth when the client supports it, verify with list_connections, then install the skills listed at the end. Never send a WhatsApp message unless the user explicitly asks for that send.

1. Authentication

OAuth 2.1 (no key to paste)

Clients that support OAuth discover everything automatically:

1. The client calls https://nivox.me/mcp and receives 401 with WWW-Authenticate: Bearer resource_metadata="https://nivox.me/.well-known/oauth-protected-resource/mcp".
2. It reads https://nivox.me/.well-known/oauth-authorization-server (RFC 8414), registers itself (Dynamic Client Registration, RFC 7591) and opens the browser at https://nivox.me/oauth/authorize.
3. The Nivox admin signs in (if needed), picks the access level and which WhatsApp numbers the client may use, and clicks Authorize.
4. The client exchanges the code (PKCE S256) at https://nivox.me/oauth/token and receives an access token — a Nivox API key. It does not expire; the admin revokes it any time on Integrations (or the client calls https://nivox.me/oauth/revoke).

Only organization admins can authorize. Metadata endpoints:

• Authorization server: https://nivox.me/.well-known/oauth-authorization-server
• Protected resource: https://nivox.me/.well-known/oauth-protected-resource/mcp
• authorization_endpoint: https://nivox.me/oauth/authorize · token_endpoint: https://nivox.me/oauth/token · registration_endpoint: https://nivox.me/oauth/register · revocation_endpoint: https://nivox.me/oauth/revoke
• Grant: authorization_code with PKCE S256; client auth none, client_secret_post or client_secret_basic; scopes read, messages, full (see §3).

API key

An admin generates a key on Integrations (https://nivox.me/app/integrations). The key looks like nvx_ + 40 hex characters and is shown once. Send it as Authorization: Bearer nvx_… (or x-api-key: nvx_… if the client cannot set Authorization). Keep it in the client's secret/env store, never in a committed file.

2. Client setup

claude.ai and Claude Desktop (custom connector, OAuth)

1. Settings → Connectors → Add custom connector.
2. Name: Nivox. Remote MCP server URL: https://nivox.me/mcp. Leave OAuth client id/secret empty (Nivox supports dynamic registration).
3. Click Add, then Connect — the Nivox authorization screen opens; sign in as an admin and click Authorize.
4. In a chat, enable the Nivox connector and ask, e.g. "list my WhatsApp conversations".

The connector appears in Claude Desktop automatically (same account). Custom connectors require a paid Claude plan (Pro, Max, Team or Enterprise).

ChatGPT (developer mode connector, OAuth)

1. Settings → Connectors → Advanced → Developer mode (enable).
2. Create a connector: Name Nivox, MCP Server URL https://nivox.me/mcp, Authentication OAuth.
3. Save, then Connect — authorize on the Nivox screen.
4. In a chat, add the Nivox connector from the tools menu ("+" → connectors).

Claude Code

OAuth (recommended):

claude mcp add --transport http nivox https://nivox.me/mcp
# then, inside Claude Code, run /mcp and choose "Authenticate" for nivox

API key alternative:

claude mcp add --transport http nivox https://nivox.me/mcp \
  --header "Authorization: Bearer nvx_YOUR_KEY"

Project-scoped .mcp.json (commit it without the key):

{ "mcpServers": { "nivox": { "type": "http", "url": "https://nivox.me/mcp" } } }

Codex CLI (OpenAI)

OAuth:

codex mcp add nivox --url https://nivox.me/mcp
codex mcp login nivox

API key in ~/.codex/config.toml (keep the key in an environment variable):

[mcp_servers.nivox]
url = "https://nivox.me/mcp"
bearer_token_env_var = "NIVOX_API_KEY"

Cursor

~/.cursor/mcp.json (or the project's .cursor/mcp.json), then accept the Authenticate prompt Cursor shows for the server:

{ "mcpServers": { "nivox": { "url": "https://nivox.me/mcp" } } }

With a key instead of OAuth: add "headers": { "Authorization": "Bearer nvx_YOUR_KEY" }.

Windsurf

~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "nivox": { "serverUrl": "https://nivox.me/mcp" } } }

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json; VS Code asks to sign in (OAuth) when the server starts:

{ "servers": { "nivox": { "type": "http", "url": "https://nivox.me/mcp" } } }

Gemini CLI

~/.gemini/settings.json:

{ "mcpServers": { "nivox": { "httpUrl": "https://nivox.me/mcp", "oauth": { "enabled": true } } } }

Any other MCP client

Generic Streamable HTTP configuration:

{ "mcpServers": { "nivox": { "type": "http", "url": "https://nivox.me/mcp",
  "headers": { "Authorization": "Bearer nvx_YOUR_KEY" } } } }

Clients that only speak stdio can bridge with npx -y mcp-remote https://nivox.me/mcp (OAuth) or npx -y mcp-remote https://nivox.me/mcp --header "Authorization: Bearer nvx_YOUR_KEY".

Verify

export NIVOX_API_KEY="nvx_..."   # the key from Integrations (skip with OAuth clients)
curl -sS https://nivox.me/mcp \
  -H "Authorization: Bearer $NIVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Then call list_connections from the client: it must return at least one connection with status: "active".

3. Access levels (scopes)

Tools above the granted scope are not listed; calling one returns an isError result with code: "forbidden". A grant or key may also be limited to specific WhatsApp numbers. User and key management, stage editing, renaming or deleting a tag, and deletions are never reachable over MCP.

Optional modules

CRM and Help Desk are switched on per organization by Nivox. A module that is off does not list its tools at all; calling one by name returns code: "module_disabled". Contacts, notes and stages (list_contacts, get_contact, add_note, list_stages…) come with either module; *_opportunity needs CRM and *_ticket needs Help Desk. Call tools/list to see what this organization actually has.

4. Tools

All ids are UUIDs returned by earlier tools. connection_id may be omitted when the credential sees a single connection. Results carry structuredContent and the same JSON as text.

Sending files (no public URL needed)

WhatsApp never needs a public link from you: Nivox uploads the bytes to Meta itself. Hand send_media the file in whichever way your client can:

1. Inline (≤ 5 MB) — file is a data: URI, the convention MCP's file-input proposals use: data:application/pdf;name=proposta.pdf;base64,JVBERi0xLjcK… (name= percent-encoded, optional). Best for code that builds the call itself; an LLM should not type base64 by hand.
2. Upload link (up to the full limit) — for a file on the agent's machine: create_media_upload(filename, conversation_id) answers upload.url, a ready curl line and file (upload:<id>). PUT the raw bytes to the link — no header needed, the link is its own credential — then call send_media(conversation_id, media_type, file: "upload:<id>"). The link works once, for one hour; the file can be sent to any conversation of the same number for 24 h, as often as needed. Needs a client that can make an HTTP request (a terminal, code execution).
3. URL — url is a public https address Nivox downloads (no private or local hosts).

# 2. upload link: the curl line from create_media_upload, with your local path
curl -sS -X PUT -H 'Content-Type: application/pdf' --data-binary @./proposta.pdf 'https://nivox.me/api/v1/uploads/<token>'

A client that can neither run code nor make an HTTP request cannot forward a file the user attached in the chat: MCP has no way yet to carry a binary from the client to the server (file inputs are an open proposal), so the model would have to retype the file byte by byte. Use a URL there, or an agent with a terminal.

CRM and Help Desk tools

Listed only when the organization has the module (§3). Every conversation carries contact_id, which is what these tools take. find_contact is the WhatsApp lookup by phone; get_contact is the customer record.

Tags are a per-organization vocabulary, not free text. Call list_tags before labelling and name a key you saw there: a name this organization does not have yet is created on the spot, so one typo becomes a permanent label nobody else uses. A contact's tags are those keys (at most 20 per contact, 200 per organization); list_contacts takes one of them as tag. Renaming or recolouring a label — and removing it from everybody — are manager actions in the Nivox app, and the key never moves when the name changes, so nothing you stored goes stale.

Editing stages and deleting contacts, deals or tickets are not MCP tools — they stay in the Nivox app (manager+). Ask the user to do it there.

Prompts offered by the server: attend_inbox, reply_to_customer, daily_summary, plus qualify_lead and triage_ticket / pipeline_review when the matching module is on. The initialize response also carries instructions — the operating guide for the granted scope and the modules this organization has.

Error results always include code. Every tool: forbidden (scope too low), module_disabled (that module is off for the organization), internal_error (unexpected). WhatsApp tools also: not_found, session_expired (24h window closed → use send_template), account_inactive, template_not_approved, unsupported_template, too_large, fetch_failed, graph_error (Meta refused; read details), upload_pending (409 — send_media got an upload whose bytes were never PUT), limit_reached (409, create_media_upload — 50 unsent uploads pending), and invalid_arguments (a malformed data: URI, both or neither of file/url, an upload of another number). CRM/Help Desk tools also: invalid_arguments (the value you gave is wrong — same code the product UI gets for the same mistake, one shared pipeline), not_found (wrong id, or another organization's row — the same answer either way, on purpose), no_stages (409 — a create/move found zero stages for that entity; only possible if every stage of a kind was deleted in the app), duplicate (409, create_contact only — that WhatsApp identity already has a contact), already_in_kind (409, convert_contact only — already that kind), limit_reached (409 — a contact already carries 20 tags, or the organization already defines 200).

5. Operating rules (what a good agent does)

• Start with list_connections; then list_conversations with unread_only: true to triage.
• Read with list_messages before answering. Reply with send_text only while window.open is true (24 hours since the customer's last message). When it is closed, the only option is an APPROVED template via send_template; the customer's reply re-opens free text.
• After answering, mark_read so the human team sees the conversation handled.
• Never message contacts with opted_out: true; never invent order, payment or delivery facts; keep messages short — WhatsApp is chat. WhatsApp formatting: *bold*, _italic_, ~strike~.
• Identity is the conversation_id; phones are display values (digits with country code).
• With CRM/Help Desk on: get_contact(contact_id) before answering (history, deals, open tickets, notes), add_note after, and create_ticket for anything you cannot resolve now. Never resolve a ticket you did not resolve, and never mark a deal won unless the user said so.

6. Skills (Agent Skills, SKILL.md)

Five skills teach agents the Nivox workflow (the CRM and Help Desk ones only matter when those modules are on). Install them into your agent's skills directory — ~/.claude/skills/<name>/SKILL.md for Claude Code, ~/.codex/skills/<name>/SKILL.md for Codex, .agents/skills/<name>/SKILL.md or the client's equivalent elsewhere:

• https://nivox.me/skills/nivox-whatsapp-attendant/SKILL.md
• https://nivox.me/skills/nivox-whatsapp-templates/SKILL.md
• https://nivox.me/skills/nivox-crm/SKILL.md
• https://nivox.me/skills/nivox-helpdesk/SKILL.md
• https://nivox.me/skills/nivox-mcp-setup/SKILL.md

One-liner (Claude Code; replace the directory for other agents):

for s in nivox-whatsapp-attendant nivox-whatsapp-templates nivox-crm nivox-helpdesk nivox-mcp-setup; do
  mkdir -p ~/.claude/skills/$s && curl -fsSL https://nivox.me/skills/$s/SKILL.md -o ~/.claude/skills/$s/SKILL.md
done

The Integrations page also offers all of them as a single zip download.

7. Troubleshooting

Security: one credential per agent, least scope that works, revoke on Integrations when an agent is retired (immediate). Every message an agent sends is stored in the team inbox and attributed to the credential that sent it.