Skip to content
Kirimdev
MCP Server

MCP Server

Kirimdev exposes a remote Model Context Protocol (MCP) server at https://api.kirimdev.com/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.

Focused, well-described tools

Send messages, browse conversations, manage contacts, create and list templates, discover phone numbers — plus multi-tenant customer tools on Business plans. The 90% of WhatsApp automation in a small, well-described surface the model can 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”

Kirimdev’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 Kirimdev 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.kirimdev.com/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.

The tools

Section titled “The tools”

The server exposes 24 tools — 19 messaging-essentials tools always available, plus 5 multi-tenant customer tools that require the Business plan (they appear in tools/list on every plan but return 402 when invoked without the entitlement).

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).
mark_as_readSend a read receipt (+ optional typing indicator) for an inbound message.
get_messageFetch a single message by msg_ id; poll delivery status / inspect failures.
list_messagesBrowse messages newest-first, with direction / status / time filters.
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.
create_contactCreate a contact on a connected account.
update_contactPatch a contact’s name / email / metadata.
list_labelsList team labels (lbl_... ids) across the org.
create_labelCreate a new label (name + preset color).
update_labelPatch a label’s name or color.
delete_labelDelete a label (removes from all contacts / conversations).
add_contact_labelAttach a label to a contact (syncs to conversations).
remove_contact_labelDetach a label from a contact (syncs to conversations).
list_templatesList Meta templates available on a phone number.
create_templateCreate a template and submit it to Meta for review.
sync_templatesPull the latest template inventory from Meta and upsert it.

Plus the customer tools (Business plan): list_customers, get_customer, create_customer, update_customer, create_customer_setup_link.

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), 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.
  • 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”