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, 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)

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