Skip to content
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 — signing in with OAuth, or using the same API key you already use for the REST API.

OAuth or API key

Paste the URL and sign in from the browser, or bring your existing kdv_live_... API key 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 invocation returns one JSON-RPC result. Long-running bulk-label work returns a job id and is polled with get_bulk_label_job; it does not keep the HTTP request open. The endpoint serves both the 2025-era protocol revisions and revision 2026-07-28 from the same URL — your client negotiates the revision it prefers and the server answers in kind, so no configuration is needed either way.

The tools

Section titled “The tools”

The server exposes 27 tools — 22 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 with attached labels, newest-first, with filters.
get_conversationSingle conversation with labels + last N messages, for thread drill-down.
search_contactsFind contacts and their labels by identity 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).
preview_bulk_label_by_messagePreview up to 10,000 contacts matching an inbound-message keyword and date range.
start_bulk_label_by_messageStart the exact confirmed preview as an asynchronous bulk-label job.
get_bulk_label_jobPoll progress and final counts for a bulk-label job.
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 accepts two kinds of credentials:

  • OAuth sign-in — OAuth-capable clients open a browser, an owner or admin signs in, picks one organization and approves mcp:read, mcp:write and/or mcp:send. See Sign in with OAuth.
  • API keys — 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 (tools/list, discovery, and read-only tools): 600 / minute

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

MCP classifies the JSON-RPC method and tool name rather than the outer HTTP method (all Streamable HTTP calls are POST). Read-only access therefore remains available when a subscription is inactive, while mutating tools return subscription_inactive until billing is restored.

Safe retries

Section titled “Safe retries”

Every mutating tool accepts an optional idempotency_key. Generate a unique key for one logical operation and reuse it only when retrying that same operation. Kirimdev replays the first successful result for 24 hours; reusing a key with different arguments returns idempotency_key_reuse.

JSON-RPC request IDs correlate requests and responses but do not deduplicate retries.

Where to next

Section titled “Where to next”