Setup

The Kirimdev MCP server is a standard remote MCP server at https://api.kirimdev.com/mcp, speaking the Streamable HTTP transport defined by the MCP spec. That means any MCP-compatible client can connect to it — Claude, OpenCode, Cursor, VSCode, Cline, Zed, Continue, MCP Inspector, etc.

There are two ways to authenticate:

• OAuth sign-in — paste the URL, sign in to Kirimdev in your browser, pick an organization and approve the permissions. No key to copy. See Sign in with OAuth.
• API key — send the same Bearer API key you use for the REST API in an Authorization header. Works with every client, including scripts and clients without OAuth support. The client tabs below use this.

Prerequisites

• An owner or admin role in the organization (OAuth), or a Kirimdev API key (kdv_live_...) from Settings → API Keys.
• At least one connected WhatsApp Business number.
• The client of your choice installed (links in each tab below).

Sign in with OAuth

Kirimdev implements the MCP authorization spec (revision 2026-07-28): the server publishes protected resource metadata, clients identify themselves with an OAuth Client ID Metadata Document, and access tokens are bound to https://api.kirimdev.com/mcp.

1. Add https://api.kirimdev.com/mcp to your client without any Authorization header. The client receives a 401 pointing at the metadata above and opens your browser.

2. Sign in to Kirimdev (email or Google). Already signed in to the dashboard? This step is skipped.

3. Pick an organization if you own or administer more than one. Each connection reaches exactly one organization; connect again to use another.

4. Choose the permissions. Each one is a checkbox on the consent page:

   Scope	Lets the client	Default
   mcp:read	Read conversations, messages, contacts, labels and templates	Always on
   mcp:write	Create and update contacts, labels, templates and customers; mark messages as read	On, can be unticked
   mcp:send	Send WhatsApp messages (send_message)	Off, tick to allow

   A tool outside the approved scopes returns 403 insufficient_scope; clients that support step-up authorization ask you again for the missing scope.

Who can connect

Only owners and admins can authorize a client, because MCP tools act across the whole organization. Membership and role are checked on every request: removing a member or demoting them to agent disconnects their clients immediately. Signing out stops the client from refreshing its access, but an access token already issued stays valid until it expires (at most one hour).

Risks to weigh before approving

• Everything the client reads — customer messages, names, phone numbers — is processed by that AI provider under its own privacy terms.
• Customer messages are untrusted text. A message containing hidden instructions could steer the AI. Keep tool approval turned on in your AI app, and only grant mcp:send if you need the AI to message customers; sent messages cannot be recalled.

Client support

Kirimdev does not offer Dynamic Client Registration (RFC 7591), which the MCP spec deprecates in favour of Client ID Metadata Documents. If a client reports a registration error during sign-in, it relies on Dynamic Client Registration — connect it with an API key instead.

Native HTTP vs. stdio bridge

Modern clients like OpenCode and Cursor speak remote MCP natively — they can hit https://api.kirimdev.com/mcp directly and forward headers. Claude Desktop still uses the stdio transport internally, so it needs the tiny mcp-remote npm bridge to translate stdio ↔ HTTP. Both paths reach the same server with the same capabilities.

Configure your client

Claude Desktop

1. Open the Claude Desktop config file.

   macOS

   open ~/Library/Application\ Support/Claude/claude_desktop_config.json

   If the file doesn’t exist, create it with {} as its content.

   Windows

   notepad $env:APPDATA\Claude\claude_desktop_config.json

   If the file doesn’t exist, create it with {} as its content.

   Linux

   ${EDITOR:-nano} ~/.config/Claude/claude_desktop_config.json

2. Add the Kirimdev MCP server entry.

   Paste the following into the JSON (merge with any existing mcpServers block):

   claude_desktop_config.json

   {
     "mcpServers": {
       "kirimdev": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://api.kirimdev.com/mcp",
           "--header",
           "Authorization:Bearer ${KIRIM_API_KEY}"
         ],
         "env": {
           "KIRIM_API_KEY": "kdv_live_REPLACE_ME"
         }
       }
     }
   }

   Replace kdv_live_REPLACE_ME with your actual API key.

   What is mcp-remote?

   Claude Desktop speaks the stdio MCP transport — it spawns a local process and pipes JSON-RPC through stdin/stdout. Kirimdev’s MCP server speaks Streamable HTTP. The mcp-remote package is a tiny stdio↔HTTP bridge maintained by the MCP community. It also injects the Authorization header on every request, which is how the Bearer token reaches Kirimdev. Make sure Node.js (so npx is available) is installed — get it from nodejs.org.

3. Restart Claude Desktop.

   Fully quit Claude (not just close the window) and reopen it. The config is read only at startup.

4. Verify the connection.

   In the Claude chat input, look for the 🔌 MCP icon at the bottom-left. Click it — you should see kirimdev listed with 11 tools available.

OpenCode

OpenCode supports remote MCP servers natively — no bridge needed.

1. Open your OpenCode config.

   Edit either the global config (~/.config/opencode/opencode.json) or a project-local one (opencode.json at the repo root). The project config wins when both exist.

2. Add the Kirimdev MCP server entry.

   opencode.json

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "kirimdev": {
         "type": "remote",
         "url": "https://api.kirimdev.com/mcp",
         "enabled": true,
         "oauth": false,
         "headers": {
           "Authorization": "Bearer ${env:KIRIM_API_KEY}"
         }
       }
     }
   }

   Then export the API key in the shell that launches OpenCode:

   macOS / Linux

   export KIRIM_API_KEY="kdv_live_REPLACE_ME"

   Add it to ~/.zshrc / ~/.bashrc to make it persistent.

   Windows

   [Environment]::SetEnvironmentVariable("KIRIM_API_KEY", "kdv_live_REPLACE_ME", "User")

   Restart your terminal after running this.

   Why oauth: false?

   OpenCode auto-detects OAuth when a remote server returns 401. With an API key in headers, "oauth": false keeps OpenCode from opening a browser. To sign in with OAuth instead, remove both "oauth": false and the headers block.

3. Restart OpenCode so it picks up the new config.

4. Verify the connection.

   Run opencode mcp list — you should see kirimdev listed as connected with 11 tools. Or just open the TUI and type a prompt that uses the tools (see Try it below).

Cursor

Cursor supports remote MCP servers via mcp.json — no bridge needed.

1. Create or open the Cursor MCP config.

   • Global (every project): ~/.cursor/mcp.json
   • Project (this repo only): .cursor/mcp.json at the project root

   If the file doesn’t exist, create it with {} as its content.

2. Add the Kirimdev MCP server entry.

   .cursor/mcp.json

   {
     "mcpServers": {
       "kirimdev": {
         "url": "https://api.kirimdev.com/mcp",
         "headers": {
           "Authorization": "Bearer ${env:KIRIM_API_KEY}"
         }
       }
     }
   }

   Then set the KIRIM_API_KEY environment variable in your shell profile (~/.zshrc, ~/.bashrc, or Windows User env vars). Cursor interpolates ${env:KIRIM_API_KEY} from the environment of the process that launched it — make sure Cursor is opened from a terminal where the variable is set, or set it system-wide.

   Project vs. global

   Use .cursor/mcp.json at the project root if you want the MCP server scoped to a specific codebase (e.g. a customer-support project that calls WhatsApp from the AI assistant). Use the global file in ~/.cursor/ if you want Kirim tools available from any Cursor window.

3. Reload Cursor.

   Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → Developer: Reload Window, or restart the app.

4. Verify the connection.

   Open Settings → Tools & MCP (or Features → Model Context Protocol on older builds). The kirimdev server should appear as connected, with 11 tools listed. Toggle them on if any default to off.

Try it

In any of the clients above, send a chat message like:

“List the WhatsApp phone numbers connected to my Kirimdev account.”

The model will call list_phone_numbers and read back the numbers and their phone_number_ids. From there you can ask it to send messages, browse conversations, look up contacts, and so on — all in natural language.

Head over to Prompting the AI for a cookbook of phrases that work well (in Indonesian and English) for each kind of task.

Security tips

API keys are sensitive

The key you wire into any MCP client can send WhatsApp messages, read every conversation, and search every contact in your organization. Practical safeguards:

• Use a dedicated key per client — label it (e.g. “Claude Desktop”, “OpenCode on laptop”, “Cursor at office”) so you can revoke just the affected key if a machine is lost.
• Prefer environment variables (${env:KIRIM_API_KEY}, ${KIRIM_API_KEY}) over hard-coding the key in JSON. Both OpenCode and Cursor support this; Claude Desktop uses the env block.
• Don’t sync the config to public git or cloud backups in plain text. .cursor/mcp.json and opencode.json are often committed — use env interpolation, not literal keys.
• Audit usage via API request logs in the dashboard — every authenticated MCP tool call admitted by the rate limiter is recorded under /mcp/tools/<tool_name> with the calling key’s last-4, status, and latency. Tool arguments and message content are not copied into the audit row. Calls made over OAuth are not shown there yet.

Troubleshooting

The client doesn’t show the kirimdev server

• Confirm the JSON file parses — paste it into jsonlint.com. A misplaced comma silently disables every server.
• For Claude Desktop: check npx is on PATH (npx -y mcp-remote --help). Install Node.js from nodejs.org if missing.
• For OpenCode / Cursor: confirm KIRIM_API_KEY is actually set in the shell that launched the client — echo $KIRIM_API_KEY (or $env:KIRIM_API_KEY on PowerShell) should print the key.
• Fully quit the client (not just close the window) before reopening — menu-bar / tray processes hold the old config.

”Invalid API key” or 401 errors

• Verify the key in the dashboard is Active (not revoked or expired).
• Check there are no quotes or whitespace inside kdv_live_.... The format is Bearer kdv_live_<26-base32-chars>.
• For Claude Desktop: the --header value must be exactly Authorization:Bearer ${KIRIM_API_KEY} with no space after Authorization:. mcp-remote parses on the first colon.
• For OpenCode with an API key: make sure "oauth": false is set. Without it, OpenCode sees the 401 and starts the OAuth flow instead of trusting your bearer header.

OAuth sign-in fails

• “No organization you can connect” — your role is agent in every organization. Ask an owner to connect the client or to make you an admin.
• The client reports a registration error — it only supports Dynamic Client Registration. Use an API key for that client.
• The connection stopped working — your role changed, you were removed from the organization, or the connection was revoked. Connect again.
• send_message returns 403 insufficient_scope — mcp:send was not ticked on the consent page. Reconnect and tick Send WhatsApp messages.

Tools call but every one returns an error

The MCP tool error response carries the same code / message / request_id envelope as the REST API. Common ones:

• whatsapp_number_not_verified — the phone_number_id you passed exists but isn’t connected. Reconnect from the dashboard.
• resource_not_found — wrong phone_number_id, or the conversation_id / contact_id belongs to a different organization.
• rate_limit_exceeded — you’re past the per-minute budget. The response includes a Retry-After-equivalent timestamp.

Claude.ai (web) and other OAuth-only clients

Web clients such as the Claude.ai Custom connector dialog accept only OAuth. Add https://api.kirimdev.com/mcp as the connector URL and follow Sign in with OAuth. If the dialog reports a client registration error, that client relies on Dynamic Client Registration, which Kirimdev does not offer — use Claude Desktop with an API key instead. Both share the same model and tool semantics.

Other MCP clients

The Kirimdev MCP endpoint is a standard Streamable HTTP server — any client that speaks the spec works. Quick pointers for clients we haven’t tested end-to-end but that follow the same pattern:

• VSCode (with the GitHub Copilot MCP extension) — workspace .vscode/mcp.json, same mcpServers shape as Cursor, but the url field is "http" typed; consult the official VSCode MCP docs.
• Cline / Continue / Zed — each ships its own settings file with a mcpServers (or equivalent) object accepting url + headers.
• MCP Inspector (for debugging) — run npx @modelcontextprotocol/inspector and configure a custom server pointing at https://api.kirimdev.com/mcp with the bearer header. This is the fastest way to confirm the server is healthy if a client misbehaves.

For ChatGPT, the “Custom GPT” Actions feature consumes our OpenAPI spec directly — MCP isn’t required for that flow.

Where to next

• Prompting the AI — what to actually say to the assistant once it’s connected. Cookbook of phrases for sending, browsing, searching, and multi-step workflows.
• Available Tools — full schema for each of the 6 tools.
• MCP Overview — what the server does, what it doesn’t expose.
• Errors — error codes shared with the REST API.