Connect KaiCalls to AI clients

At a glance

MCP server URL

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

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

calls:read, calls:write, agents:read

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

Public code

The public SDK, plugin, and MCP connector repos live under the KaiCalls GitHub organization. The private product repository stays private; these repos contain the code and metadata intended for developers 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)

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.

1. Open Settings → Connectors → Add custom connector.
2. Paste the MCP server URL: https://www.kaicalls.com/api/mcp.
3. Approve the KaiCalls OAuth consent screen when Claude opens it.
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.

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

ChatGPT (Developer Mode)

1. Enable Settings → Connectors → Advanced → Developer mode.
2. Add a connector with the MCP server URL https://www.kaicalls.com/api/mcp.
3. Complete the OAuth sign-in flow with your KaiCalls account.

ChatGPT requires OAuth (it does not accept pasted API keys). The ChatGPT connector callback pattern is allowlisted on the KaiCalls authorization server.

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

Add KaiCalls 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 server URL https://www.kaicalls.com/api/mcp. Le Chat auto-detects the transport and OAuth.
3. Complete the OAuth flow and share the connector with your team as needed.

xAI Grok (Business / Enterprise)

In Grok's connector management, add a remote MCP server:

• URL: https://www.kaicalls.com/api/mcp
• Transport: Streamable HTTP
• Auth: OAuth, or a Bearer header Authorization: Bearer kc_live_…
• Allowlist the tools you want Grok to use (start with read-only tools).

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 OAuth, an API key, or no auth, then complete sign-in.

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