Connect KaiCalls to Claude, ChatGPT, Grok, Manus & every MCP client

At a glance

MCP server URL

https://www.kaicalls.com/api/mcp

ChatGPT app

KaiCalls in the ChatGPT app directory (published, no setup needed)

Transport

Streamable HTTP (POST JSON-RPC 2.0)

Auth

OAuth 2.1 (authorization code + PKCE S256, refresh tokens, Dynamic Client Registration) for hosted chat clients; or a KaiCalls API key (kc_live_…) Bearer token for developer/CLI clients.

Scopes

21 scopes across agents, billing, calls, evals, events, knowledge, leads, numbers, products, sms, support, webhooks. Each tool's required scope is listed in the table below.

Discovery

/.well-known/mcp.json, /.well-known/mcp/server-card.json, /.well-known/oauth-protected-resource

Get an API key (for Bearer-token clients) from the dashboard. For OAuth-based clients you approve the KaiCalls consent screen during setup — no key to paste.

For a no-OAuth MCP setup, create a key with agents:read and calls:read. Add calls:write only for trusted clients that should be allowed to place real outbound calls.

Direct MCP clients can send the key as Authorization: Bearer kc_live_.... Gateways that collect API keys separately can send the same key as X-KaiCalls-API-Key: kc_live_....

OAuth callback URLs (native clients)

Dynamic Client Registration (POST /api/oauth/register) accepts either callback mechanism a desktop MCP client offers:

• A private-use URI scheme per RFC 8252 §7.1 — e.g. cursor://anysphere.cursor-mcp/oauth/callback or vscode://….
• A loopback HTTP listener per RFC 8252 §7.3 — http://localhost:PORT/… or http://127.0.0.1:PORT/… on any port.
• Any https:// callback, for hosted/web clients.

Plain http:// callbacks to non-loopback hosts, and script-capable schemes (javascript:, data:, blob:, file:, vbscript:), are rejected with invalid_client_metadata.

Public code

The public SDK, plugin, WordPress source, n8n, and MCP connector repos live under the KaiCalls GitHub organization. The approved WordPress plugin installs from WordPress.org. The private product repository stays private; these repos contain the code and metadata intended for developers, answer engines, and connector directories.

Available tools

Every client below exposes the same tool inventory. Read-only tools are safe to enable broadly; make_call places real outbound phone calls, so treat it as a write / external-effect action and enable it deliberately.

Using the tools well

Claude (Claude.ai & Desktop)

1. Open Settings → Connectors (this link goes straight there), then Add custom connector.
2. Paste the KaiCalls connector URL: https://www.kaicalls.com/api/mcp.
3. Sign in with your KaiCalls account and approve the access Claude asks for.
4. Enable the tools you want. To start safely, enable read-only tools first and add make_call once you're ready to place calls.

On Team and Enterprise plans, an organization owner adds the connector first under Organization settings → Connectors; members then connect it from their own Connectors settings. Claude connects from Anthropic's cloud, so the KaiCalls server being publicly reachable is already taken care of.

For Claude Code, install the same remote server from a terminal:

bash
claude mcp add --transport http --scope user kaicalls https://www.kaicalls.com/api/mcp
claude mcp list

If Claude Code shows kaicalls - Needs authentication, start an interactive Claude Code session, run /mcp, select kaicalls, and choose authenticate. That opens the KaiCalls OAuth flow and stores the token in Claude.

To skip OAuth and use a static KaiCalls API key instead, pass the Bearer header when you add the server:

bash
claude mcp add --transport http --scope user kaicalls-api https://www.kaicalls.com/api/mcp \
  -H "Authorization: Bearer kc_live_xxxxx"
claude mcp list

A read-only key should use agents:read and calls:read. Include calls:write only if Claude Code should be able to use make_call.

Claude's OAuth callback (claude.ai/api/mcp/auth_callback) is already allowlisted by the KaiCalls authorization server.

ChatGPT (published app or Developer Mode)

Option 1 — Install the KaiCalls app (recommended, all plans)

KaiCalls is a published, OpenAI-approved app in the ChatGPT directory. This is the fastest path — no developer settings required, and it works on every ChatGPT plan, including Free.

1. Open the KaiCalls app listing in ChatGPT (or search for "KaiCalls" in the ChatGPT app directory).
2. Click Connect and sign in with your KaiCalls account.
3. Approve the permissions and pick the business to connect. Then just ask — "List my recent calls" — or @-mention KaiCalls in a conversation.

On ChatGPT Business, Enterprise, and Edu workspaces an admin must enable the app first under Workspace settings → Apps.

Option 2 — Add the MCP server in Developer mode (paid plans)

1. Enable Settings → Security and login → Developer mode (also reachable via the connectors/apps settings under Advanced).
2. Add a connector with the KaiCalls URL https://www.kaicalls.com/api/mcp.
3. Sign in with your KaiCalls account when prompted.

ChatGPT always signs in through your KaiCalls account; it does not accept pasted API keys. Its connector callback pattern is allowlisted on the KaiCalls authorization server. Write actions — like placing an outbound call — always ask for confirmation before running.

Claude Code

Add the connector once from the CLI, then authenticate:

bash
claude mcp add --transport http kaicalls https://www.kaicalls.com/api/mcp
# then, inside Claude Code:
/mcp

To share it with a repo instead of your user profile, add --scope project — that writes a .mcp.json your teammates pick up automatically:

json
{
  "mcpServers": {
    "kaicalls": {
      "type": "http",
      "url": "https://www.kaicalls.com/api/mcp"
    }
  }
}

For headless runs (CI, cron, a container with no browser to complete OAuth in), skip the interactive sign-in and pass a KaiCalls API key instead: claude mcp add --transport http kaicalls https://www.kaicalls.com/api/mcp --header "Authorization: Bearer kc_live_…"

OpenAI Codex

Add KaiCalls to ~/.codex/config.toml:

toml
[mcp_servers.kaicalls]
url = "https://www.kaicalls.com/api/mcp"

Or add it from the CLI with codex mcp add kaicalls --url https://www.kaicalls.com/api/mcp. Codex completes the OAuth sign-in on first use.

Codex's support for remote (streamable-HTTP) MCP servers is version-dependent. If your build only accepts local command servers, or the entry above is ignored, bridge to it with mcp-remote:

toml
[mcp_servers.kaicalls]
command = "npx"
args = ["-y", "mcp-remote", "https://www.kaicalls.com/api/mcp"]

For non-interactive runs, set a KaiCalls API key as a bearer header rather than relying on the browser OAuth flow.

Provisioning many accounts from a coding agent

Agencies and MSPs are the main reason to attach KaiCalls to a coding agent rather than a chat client: the agent can read your own client roster and set each one up. With the connector attached, a single instruction covers the whole job —

Read clients/roster.yaml. For every client without a kaicalls_number,
create a secretary using the prompt in templates/intake.md, buy a local
number in their area code, attach it, point the webhook at our staging
endpoint, and write the number back to the roster.

That runs create_agent, search_available_numbers, buy_number, attach_number, and set_webhook per client. Two related patterns worth knowing:

• Keep prompts in git. update_agent_config deploys a change, list_config_versions and rollback_config are the undo — every deploy is hashed and versioned, so reverting is a real operation rather than a re-edit.
• Test in CI. run_eval executes the saved voice scenarios for an agent, so a reworded greeting can't silently break the booking flow. Gate the merge on it.

For a first-time buyer who has no account yet, point the agent at the narrowed setup endpoint https://www.kaicalls.com/api/mcp/acquisition instead — same auth, restricted to the tools that take someone from no account to a number that answers.

VS Code & GitHub Copilot

Add an entry to .vscode/mcp.json (workspace) or your user settings:

json
{
  "servers": {
    "kaicalls": {
      "type": "http",
      "url": "https://www.kaicalls.com/api/mcp"
    }
  }
}

VS Code triggers the OAuth flow on first use. For non-interactive setups, pass a Bearer token instead via a headers entry ("Authorization": "Bearer kc_live_…").

Cursor

One click — add KaiCalls to Cursor. Cursor opens with the connector prefilled; approve it and sign in.

Or add it by hand to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

json
{
  "mcpServers": {
    "kaicalls": {
      "url": "https://www.kaicalls.com/api/mcp"
    }
  }
}

Cursor handles the OAuth handshake automatically. You can also add an "headers": { "Authorization": "Bearer kc_live_…" } block to use a static API key.

Windsurf

Add KaiCalls to ~/.codeium/windsurf/mcp_config.json:

json
{
  "mcpServers": {
    "kaicalls": {
      "serverUrl": "https://www.kaicalls.com/api/mcp"
    }
  }
}

Reload Cascade's MCP servers, then authorize KaiCalls when prompted.

Mistral Le Chat

1. A workspace admin opens Settings → Connectors → Add MCP connector.
2. Enter the KaiCalls connector URL https://www.kaicalls.com/api/mcp. Le Chat detects the rest automatically.
3. Sign in with your KaiCalls account, then share the connector with your team as needed.

xAI Grok

1. Go to grok.com/connectors and click New Connector, then select Custom.
2. Enter the KaiCalls connector URL https://www.kaicalls.com/api/mcp.
3. Sign in with your KaiCalls account when Grok prompts you — or, for an unattended setup, paste an API key as a Bearer header Authorization: Bearer kc_live_….
4. Grok discovers the KaiCalls tools automatically. Allowlist the ones you want (start with read-only tools).

Grok connects from xAI's cloud, and the KaiCalls connector is already publicly reachable over HTTPS — there is nothing to expose or tunnel from your own machine. Grok Business / Enterprise admins can manage connectors org-wide from the same connector management surface.

Manus

1. Create a KaiCalls API key in the dashboard (Settings → API Keys). For a safe start, scope it to agents:read and calls:read.
2. In Manus, open Settings → Integrations → Custom MCP Servers → Add Server.
3. Enter a server name (e.g. KaiCalls), the server URL https://www.kaicalls.com/api/mcp, and your API key (kc_live_…) as the Bearer token.
4. Manus tests the connection and lists the KaiCalls tools alongside its built-in integrations. Try "List my recent KaiCalls calls" to confirm.

Add calls:write to the key only if Manus should be able to place real outbound calls with make_call.

Google Gemini (app & CLI)

In the consumer Gemini app, custom MCP connectors are available inside Gemini Spark: open Settings & help → Connected Apps on gemini.google.com and paste https://www.kaicalls.com/api/mcp into Add a custom app link (personal Google accounts, web-first; then available on mobile too).

For the Gemini CLI, add the server from a terminal:

bash
gemini mcp add --transport http kaicalls https://www.kaicalls.com/api/mcp \
  --header "Authorization: Bearer kc_live_xxxxx"

Omit the header to use OAuth instead — the CLI discovers the KaiCalls authorization server automatically on the first 401 and walks you through sign-in.

Perplexity

1. Open Settings → Connectors → Add Connector → Custom MCP.
2. Enter a name, the server URL https://www.kaicalls.com/api/mcp, and the transport (Streamable HTTP).
3. Choose sign-in (OAuth) or an API key, then complete it with your KaiCalls account.

Enterprise admins can share the connector org-wide; member-added connectors may be disabled by default.

Smithery

KaiCalls is listed on Smithery. Install from that listing or publish the remote server yourself with the canonical MCP URL.

For a self-managed Smithery deployment, add a config schema so Smithery prompts users for a KaiCalls API key and forwards it as a header:

bash
smithery mcp publish "https://www.kaicalls.com/api/mcp" -n @kaicalls/kaicalls \
  --config-schema '{"type":"object","properties":{"kaiCallsApiKey":{"type":"string","title":"KaiCalls API Key","description":"Create a KaiCalls API key with agents:read and calls:read. Add calls:write only if this Smithery connection may place outbound calls.","x-from":{"header":"x-kaicalls-api-key"},"x-to":{"header":"X-KaiCalls-API-Key"}}},"required":["kaiCallsApiKey"]}'

Smithery can list the public tool catalog without credentials. Add the config schema above so users can save a KaiCalls API key for authenticated tools/call requests.

Developer clients (Z.ai, Hermes, OpenClaw)

KaiCalls also works with developer/agent runtimes that consume MCP servers. For Z.ai, reference it as an MCP tool source in a chat/completions request:

json
{
  "tools": [
    {
      "type": "mcp",
      "server_label": "kaicalls",
      "server_url": "https://www.kaicalls.com/api/mcp",
      "transport_type": "streamable-http",
      "allowed_tools": ["list_recent_calls", "get_transcript"],
      "headers": { "Authorization": "Bearer kc_live_…" }
    }
  ]
}

Hermes Agent (~/.hermes/config.yaml) and OpenClaw (openclaw mcp add kaicalls --url https://www.kaicalls.com/api/mcp) both accept the same URL with either an Authorization header or auth: oauth. Start with read-only tools and enable outbound/write tools explicitly.

Verify with MCP Inspector

Before wiring up a client, confirm the server with the official inspector:

bash
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: https://www.kaicalls.com/api/mcp
# tools/list works without auth; run OAuth or add an API key before tools/call

You can also confirm the advertised inventory with curl https://www.kaicalls.com/.well-known/mcp.json.

Troubleshooting first setup

Frequently asked questions