Skip to content
kirim.dev
MCP Server

MCP Server

Kirim exposes a remote Model Context Protocol (MCP) server at https://api.kirim.chat/mcp so AI assistants can send WhatsApp messages, search contacts, and browse conversations on your behalf — using the same API key you already use for the REST API.

Same auth as /v1

Bring your existing kdv_live_... API key. No OAuth dance, no extra signup. Generate keys from the dashboard exactly like REST.

Six focused tools

Send messages, list/get conversations, search contacts, list templates, discover phone numbers. The 90% of WhatsApp automation in six well-described tools — small enough for the model to use confidently.

Works with major clients

Claude Desktop, ChatGPT, Cursor, VSCode, MCP Inspector — anything that speaks the MCP Streamable HTTP transport (spec 2025-03-26+).

Same rate limits & isolation

Per-organization token bucket, same as /v1. Tools resolve phone_number_id through the same multi-tenant fence — keys from other orgs cannot see or send from your numbers.

What it does

Section titled “What it does”

Kirim’s MCP server is a thin protocol adapter on top of the existing Public API. Each MCP tool maps to a /v1 endpoint and reuses the same validation, multi-tenant scoping, error catalogue, and realtime side effects (BullMQ jobs, WebSocket publish, audit logs).

The result is that an AI assistant connected to your Kirim account can:

  • Send WhatsApp messages — text, image, document, video, audio, template, or interactive (CTA / list / carousel).
  • Browse conversations — list recent chats, drill into a single conversation with its message history.
  • Look up contacts — search by phone (E.164) or by name / email.
  • Discover what’s available — list connected phone numbers and approved Meta templates.

Endpoint

Section titled “Endpoint”
POST https://api.kirim.chat/mcp
Authorization: Bearer kdv_live_...
Content-Type: application/json
Accept: application/json, text/event-stream

The transport is MCP Streamable HTTP in stateless mode: every request is self-contained, no Mcp-Session-Id is issued, and the server uses single-shot JSON responses (no SSE upgrade) because every tool is synchronous.

Six tools

Section titled “Six tools”
ToolPurpose
list_phone_numbersDiscover connected WhatsApp numbers + their phone_number_id. Call this first.
send_messageSend a WhatsApp message (text / image / document / video / audio / template / interactive).
list_conversationsList conversations on a phone number, newest-first, with filters.
get_conversationSingle conversation + last N messages, for thread drill-down.
search_contactsFind a contact by phone or name/email substring.
list_templatesList Meta-approved templates available on a phone number.

See Available Tools for the full schema of every tool, including input arguments and example responses.

Quick example

Section titled “Quick example”

Once connected (see Setup with Claude), you can ask the assistant in plain language:

“Send a WhatsApp to +628123456789 saying the package arrives tomorrow.”

The model will (typically):

  1. Call list_phone_numbers to find the sending account.
  2. Call send_message with to, type: "text", and the body you asked for.
  3. Report back with the new msg_... id and its status.

You never write a tool call directly — the model picks the right tool from the natural-language request. See Prompting the AI for a cookbook of phrases that work well in Indonesian and English.

Authentication

Section titled “Authentication”

MCP uses the same Bearer API keys as the REST /v1 API. Generate a key from the dashboard (Settings → API Keys), then configure your MCP client to send it as Authorization: Bearer kdv_live_....

What’s not exposed

Section titled “What’s not exposed”

The MCP surface is deliberately narrower than /v1. The following are not (yet) MCP tools, and you should keep using the REST API or dashboard for them:

  • Webhooks — subscriptions, deliveries, replay. Managed via dashboard or /v1/webhook_subscriptions.
  • Labels — create / update / delete. Available via REST.
  • Bulk operations — broadcasts, bulk label, contact import.
  • Account onboarding — embedded signup, phone-number connect.
  • Admin / billing — out of scope for assistant-driven flows.

If you have a strong use case for one of these, open an issue — we ship MCP tools demand-first to keep the surface small enough for the model to use accurately.

Limits

Section titled “Limits”

The MCP endpoint shares the same per-organization token bucket as /v1. Default Starter plan limits:

  • Write (e.g. send_message): 60 / minute
  • Read (everything else): 600 / minute

X-RateLimit-* headers ride on every MCP response, same shape as the REST endpoints. See Rate Limits for the full tier table.

Where to next

Section titled “Where to next”