Setup with Claude

There are two ways to connect Claude to the Kirim MCP server, depending on which Claude product you use:

• Claude Desktop — local config file + the mcp-remote bridge. Works with the Bearer API key Kirim already issues. Recommended.
• Claude.ai (web) — the “Custom Connector” UI. Requires OAuth, which Kirim’s MCP does not implement yet.

This guide covers Claude Desktop end-to-end. ChatGPT, Cursor, and VSCode follow the same mcp-remote pattern with slightly different config locations — see Other clients at the bottom.

Prerequisites

• Claude Desktop app (latest version) — download here.
• Node.js installed (for npx), or Bun.
• A Kirim API key (kdv_live_...). Generate one from the dashboard under Settings → API Keys.
• At least one connected WhatsApp Business number.

Connect 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 Kirim MCP server entry.

   Paste the following into the JSON (merge with any existing mcpServers you already have):

   claude_desktop_config.json

   {
     "mcpServers": {
       "kirim": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://api.kirim.chat/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. Kirim’s MCP server speaks Streamable HTTP. The mcp-remote package is a tiny stdio↔HTTP bridge maintained by the MCP community. It also handles injecting the Authorization header on every request, which is how the Bearer token reaches Kirim.

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 kirim listed with 6 tools available. If the entry shows an error, jump to Troubleshooting below.

5. Try it.

   Send Claude a message:

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

   Claude 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 in claude_desktop_config.json is plain text. Anyone with read access to your machine can use it to send WhatsApp messages on behalf of your organization. Practical safeguards:

• Use a dedicated key labelled “Claude Desktop” — don’t reuse a production server key.
• Revoke immediately if your laptop is lost / shared / stolen.
• Don’t sync the config to git or cloud backups in plain text.
• Audit usage via API request logs in the dashboard — every MCP tool call shows up there with the calling key’s last-4.

Troubleshooting

Claude doesn’t show the kirim server

• Confirm the JSON file parses — paste it into jsonlint.com. A misplaced comma silently disables every server.
• Check npx is on PATH: in a terminal, run npx -y mcp-remote --help. If npx isn’t found, install Node.js from nodejs.org.
• Fully quit Claude (Cmd+Q on macOS, right-click tray icon → Quit on Windows) before reopening — the menu-bar process holds 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>.
• Make sure the --header value is exactly Authorization:Bearer ${KIRIM_API_KEY} with no space after Authorization:. mcp-remote parses on the first colon.

Tools call but every one returns an error

Open the tool’s error response in Claude — it 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) — not supported yet

The Custom connector dialog in Claude.ai web only accepts OAuth credentials. Kirim’s MCP currently authenticates via Bearer API keys only, so the web UI flow cannot complete. We’re tracking demand for adding OAuth 2.1 with Dynamic Client Registration (RFC 7591) — if you need this for your team, let us know.

In the meantime, use Claude Desktop for production assistant use cases. The two products share the same model and tool semantics; only the UI shell differs.

Other clients

The same mcp-remote pattern works for any client that speaks stdio MCP. Pointers:

• Cursor — ~/.cursor/mcp.json (same JSON shape).
• VSCode (with the MCP extension) — workspace .vscode/mcp.json.
• MCP Inspector (for debugging) — run npx @modelcontextprotocol/inspector and configure a custom server pointing at https://api.kirim.chat/mcp with the bearer header.

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 Claude 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.