kaicalls-mcp

# KaiCalls MCP Server

> **A business phone line with a secretary: get a number, answer missed calls, take messages, read calls.**

Get a business number (or keep yours) with Kai built in. Your phones ring first; Kai
answers misses and after-hours calls, takes the details and texts you. See
[current plans and pricing](https://www.kaicalls.com/pricing).
This repository is the **public connector definition** for the hosted KaiCalls MCP
server — it documents the endpoint, authentication, and tool catalog so MCP clients
and directories can discover and connect to it.

The KaiCalls platform itself is a hosted SaaS — there is no server to install. You
connect to the live endpoint below with your KaiCalls account.

| | |
|---|---|
| **MCP endpoint** | `https://www.kaicalls.com/api/mcp` |
| **Transport** | Streamable HTTP (JSON-RPC over HTTP POST) |
| **Auth** | OAuth 2.1 (PKCE S256 + DCR) **or** `kc_live_` API key as Bearer |
| **Setup endpoint** | `https://www.kaicalls.com/api/mcp/acquisition` (setup-only subset for first-time buyers) |
| **Tools** | 79 on the account endpoint (43 read-only, 36 write/setup); 37 on the setup endpoint |
| **Homepage** | [KaiCalls](https://www.kaicalls.com?utm_source=mcp_registry&utm_medium=directory) |
| **Provider** | [KaiCalls](https://www.kaicalls.com) · connor@kaicalls.com |
| **License** | [MIT](LICENSE) (connector definitions and docs) |
| **Status** | GA — live in production |

---

## Quick Answer

**What is the KaiCalls MCP connector?** It is the official hosted MCP connector for KaiCalls. Existing customers use `https://www.kaicalls.com/api/mcp`; a first-time buyer can use the setup-only surface at `https://www.kaicalls.com/api/mcp/acquisition`.

**Who should use it?** Use it when Claude, ChatGPT, Cursor, an MCP gateway, or another AI client needs to safely inspect KaiCalls agents, calls, transcripts, leads, analytics, and approved setup actions.

**Does it require hosting your own server?** No. KaiCalls hosts the MCP server. Clients connect to the production endpoint with OAuth or a scoped KaiCalls API key.

**Is this the WordPress plugin?** No. The approved [KaiCalls AI Intake plugin](https://wordpress.org/plugins/kaicalls-ai-intake/) captures website leads from WordPress. This repo documents the agent/MCP connector.

**Is this the n8n integration?** No. n8n workflows should use [n8n-nodes-kaicalls](https://github.com/KaiCalls/n8n-nodes-kaicalls).

---

## Quick connect

### Claude (web & desktop) / ChatGPT
Add a custom connector pointing at `https://www.kaicalls.com/api/mcp` for an existing
account, or the acquisition endpoint for setup. Sign in with your KaiCalls account,
pick the business on the consent screen, and Allow. See
[`docs/quickstart.md`](docs/quickstart.md) for screenshots and per-client steps.

### API-key clients / MCP gateways
Pass a KaiCalls API key directly — no OAuth round-trip needed:

```
Authorization: Bearer kc_live_xxxxxxxxxxxxxxxxxxxx
```

(`X-KaiCalls-API-Key: kc_live_...` is also accepted.) Generate keys in the KaiCalls
dashboard under **Settings → API Keys**. See [`docs/authentication.md`](docs/authentication.md).

### Cline / remote MCP clients
KaiCalls is a remote server — there is nothing to clone or install. Add it to your
MCP client config as a Streamable HTTP server and authenticate with a `kc_live_` key.
For Cline, edit `cline_mcp_settings.json` (or use the **Remote Servers** tab) and add:

```json
{
  "kaicalls": {
    "url": "https://www.kaicalls.com/api/mcp",
    "type": "streamableHttp",
    "headers": { "Authorization": "Bearer kc_live_YOUR_KEY" }
  }
}
```

Replace `kc_live_YOUR_KEY` with a key from the KaiCalls dashboard under **Settings →
API Keys**. The transport type must be the camelCase string `streamableHttp` — using
`streamable-http` or omitting it makes Cline fall back to SSE and the connection fails
with a `405`. Once saved, Cline lists the KaiCalls tools and is ready to use. See
[`llms-install.md`](llms-install.md) for the full agent-driven setup walkthrough.

---

## Gemini CLI and Antigravity

```bash
gemini extensions install https://github.com/KaiCalls/kaicalls-mcp
agy plugin install https://github.com/KaiCalls/kaicalls-mcp
```

Both connect to the hosted server at `https://www.kaicalls.com/api/mcp` and sign
you in with OAuth the first time a tool runs.

## Run locally over stdio (Docker)

Most clients should connect to the hosted server at `https://www.kaicalls.com/api/mcp`. For stdio-only clients, this repo ships a small bridge with no dependencies:

```bash
docker build -t kaicalls-mcp .
docker run -i --rm -e KAICALLS_API_KEY=kc_live_... kaicalls-mcp
# or without Docker: KAICALLS_API_KEY=kc_live_... node stdio-proxy.mjs
```

`initialize` and `tools/list` work without a key. `tools/call` needs `KAICALLS_API_KEY`, which you create at https://www.kaicalls.com/dashboard/settings/api-keys.

## Tools

The account endpoint exposes 79 tools: 43 read-only and 36 write/setup. Every tool carries MCP
safety annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
The setup endpoint (`/api/mcp/acquisition`) exposes the 37 tools marked Yes in the
**Setup surface** column, the subset that takes a new business from signup to a working number.
The machine-readable inventory, with full descriptions, scopes and annotations, is in
[`mcp.json`](mcp.json) and [`server-card.json`](server-card.json). In-depth notes for the core
tools are in [`docs/tools.md`](docs/tools.md). The live `tools/list` response returns each tool's
input schema.

### Read-only tools (43)

| Tool | Scope | Setup surface | What it does |
|------|-------|:-------------:|--------------|
| `get_extra_number_status` | `numbers:read` | Yes | Read an owner-authorized extra-number request. |
| `get_setup_recovery_status` | `numbers:read` | Yes | Read an owner-authorized setup recovery request by its business and idempotency key. |
| `check_call_status` | `calls:read` |  | Check the status of a call by its ID |
| `list_recent_calls` | `calls:read` |  | List recent calls for the authenticated business |
| `get_transcript` | `calls:read` |  | Get the transcript and summary of a completed call |
| `get_call_recording` | `calls:read` |  | Get the real call recording URL for a call so reviewers can listen to the voice/audio instead of relying only on the transcript. |
| `list_agents` | `agents:read` | Yes | List the KaiCalls agents on the authenticated account. |
| `get_business_info` | `agents:read` | Yes | Read back what a business already has: profile details, how many agents are configured, and recent call volume. |
| `get_operational_settings` | `agents:read` | Yes | Audit the business-level operational setup required before changing a live account: staff alert recipients, SMS/email alert flags, escalation rules, textable send-link entries, and assigned agent voice/model/greeting metadata. |
| `get_activation_status` | `agents:read` | Yes | Read the persisted proof-first activation status for one accessible business. |
| `list_leads` | `calls:read` |  | List leads for the authenticated business, with optional status/source/agent filters. |
| `get_lead` | `calls:read` |  | Get full details for a single lead by ID, including the latest AI lead score and explanation. |
| `list_voicemails` | `calls:read` |  | List recent voicemails for the authenticated business, including transcripts and recording URLs. |
| `list_sms_messages` | `calls:read` |  | List recent SMS messages for the authenticated business. |
| `list_campaigns` | `calls:read` |  | List outbound call campaigns for the authenticated business. |
| `list_workflow_templates` | `calls:read` |  | List the cadence/campaign workflow templates KaiCalls can run (standard, aggressive, nurture, custom), including each template's retry interval, defaults (call windows, days, attempts), and a ready-to-use cadence_config example. |
| `get_analytics` | `calls:read` |  | Get a dashboard summary (lead counts by status, conversion rate, call volume and duration, top agents, and business outcomes by type) over a recent time window. |
| `get_usage` | `events:read` | Yes | List recent API usage events (endpoint, method, status code, cost) for the caller's account. |
| `list_plans` | `billing:read` | Yes | Read the canonical public KaiCalls plan catalog, monthly USD prices and allowances. |
| `get_checkout_status` | `billing:read` | Yes | Read a Stripe-verified subscription checkout receipt for a business you own. |
| `get_balance` | `billing:read` |  | Get plan terms and usage for accessible businesses. |
| `list_numbers` | `numbers:read` | Yes | List phone numbers assigned to the accessible business(es), with capability and compliance flags. |
| `get_phone_flow` | `numbers:read` | Yes | Read how calls ring on the business's hosted phone system: which cells and desk phones ring, for how many seconds, and whether after-hours callers go straight to the AI receptionist. |
| `get_phone_system_status` | `numbers:read` | Yes | Read whether the business's hosted phone system is set up: Kai's extension, the team ring group and dial plan ids (never secrets), the phone-system line, and `next_step` — the one line to relay to the owner. |
| `list_conversations` | `sms:read` |  | List SMS conversation threads (counterparty timeline metadata) for the authenticated business, most recent first. |
| `get_conversation` | `sms:read` |  | Get a single SMS conversation thread by ID. |
| `get_webhook` | `webhooks:read` |  | List the configured outbound webhook(s) for a business, including supported event types. |
| `list_evals` | `evals:read` |  | List canned mock-conversation eval scenarios for an agent (or all accessible agents). |
| `list_voices` | `agents:read` | Yes | List the curated, credential-free voice catalog (id, display name, accent, language, gender, sample URL) used to configure agent voices. |
| `search_available_numbers` | `numbers:read` | Yes | Search the carrier for phone numbers available to purchase (real-tim