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. — using the same Bearer API key you already use for the REST API.

This page covers the three clients we test against. The pattern is the same everywhere: point your client at the URL, send the API key in an Authorization header, restart, and start prompting.

Prerequisites

• A Kirimdev API key (kdv_live_...). Generate one from the dashboard under Settings → API Keys.
• At least one connected WhatsApp Business number.
• The client of your choice installed (links in each tab below).

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. Kirimdev MCP authenticates with Bearer API keys, not OAuth, so we explicitly disable the OAuth flow to keep OpenCode from trying to open a browser for authorization.

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 MCP tool call shows up there with the calling key’s last-4.

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: make sure "oauth": false is set. Without it, OpenCode sees the 401 and tries to start an OAuth flow instead of trusting your bearer header.

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) — not supported yet

The Custom connector dialog in Claude.ai web only accepts OAuth credentials. Kirimdev’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 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.