# CallMCP
> Phone calls as an MCP tool. CallMCP gives an AI agent a real phone line — outbound/inbound calling, SMS, transcripts, recordings, webhooks, and phone-number management — exposed as standard MCP tools instead of a bespoke telephony integration.

This file is a machine-readable index of callmcp.ai, written for an AI agent (or a crawler building one) to read BEFORE a human does. Connection facts come first because that's what an agent needs to act; the page index and tool inventory follow. Every fact below traces to a real file in the CallMCP/KaiCalls codebase — nothing here is aspirational or invented. Format convention (not content) borrowed from kaicalls.com/llms.txt; this is a different product/audience and none of its copy is reused.

## Connect now (protocol facts first)
- Skill file (versioned, self-contained onboarding for an agent — start here): `https://callmcp.ai/skill.md`
- MCP endpoint: `https://callmcp.ai/mcp` — POST, JSON-RPC 2.0, `streamable-http` transport (proxied by a Next.js rewrite to the real backend, `https://www.kaicalls.com/api/mcp`; same server, same tool handlers). `stdio` is also supported for local development.
- Discovery documents (unauthenticated, safe to crawl): `https://callmcp.ai/.well-known/mcp.json` and `https://callmcp.ai/.well-known/mcp/server-card.json` — both proxied the same way to the live backend. They enumerate the full tool catalog with JSON Schema + safety annotations, generated from the same source (`getDiscoveryTools()`) the live `tools/list` response uses, so discovery and runtime never drift apart.
- Handshake: `initialize` (protocol version + server info) and `tools/list` (full tool catalog) are both unauthenticated by design — a client or directory crawler can see what the server offers before deciding to connect. `tools/call` is where auth and per-tool scope are enforced.
- Auth: `Authorization: Bearer kc_live_...` on every `tools/call`. Each tool requires an OAuth2-style scope (see Scopes below) checked against the key.
- Get a key without a human: `POST https://www.kaicalls.com/api/v1/signup` is a real, unauthenticated, agent-callable endpoint (5 req/hour/IP). Send `{ business_name, email }` (both required), get back an HTTP 402 with an x402 payment challenge (USDC on Base, facilitated by Stripe Machine Payments — `network: eip155:8453`), pay, retry with `PAYMENT-SIGNATURE` + `X-Payment-Challenge` headers, and the response carries `api_key`, `business_id`, `agent_id`, and `phone_number` already provisioned in the same round trip. A non-x402 fallback (`provisioning_deferred: true` + a Stripe Checkout `checkout_url` for a human) exists in the code but is not the live path today — x402 is enabled in production. Full request/response shapes: `/connect`.
- Risk annotations an agent should read before calling anything: every tool carries `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` in its schema. `make_call` and `buy_number` are both `destructiveHint: true`. `make_call` executes immediately on a valid scoped key — no server-side approval gate, annotation-only (client must honor it). `buy_number` is stricter: because a purchase is carrier-billed the moment it executes, it now runs through the same authority-gated broker as the config-changing tools below — without a satisfied `authority` envelope it executes nothing and returns a `pending_approval` record instead. Config-changing tools (`update_agent_config`, `configure_agent_business_rules`, `request_kaicalls_update`, `rollback_config`) go further: they require an `idempotency_key`, and high-impact fields require an `authority` envelope (`human_confirmed` / `dashboard_session` / `system_policy`) or `queue_for_approval: true`. Full breakdown, including gaps: `/safety`.

## Pages
- [Home](https://callmcp.ai/): Product overview, a live terminal recording of a real `tools/list` call against production, the tool-inventory grid with real schemas, and the signup snippet.
- [Connect Your Agent](https://callmcp.ai/connect): The real programmatic signup flow — `POST /api/v1/signup`, the x402 402-payment challenge, the Stripe Checkout fallback — with exact request/response bodies.
- [MCP Server for Phone Calls](https://callmcp.ai/mcp-server-for-phone-calls): Full tool reference — schemas, a sample `tools/call`, transcript retrieval, the approval/authority model for config writes, webhook event types + HMAC verification, and number search/buy/attach.
- [What Is an MCP Server?](https://callmcp.ai/what-is-an-mcp-server): MCP protocol primer — tools/resources/prompts, the initialize→tools/list→tools/call handshake, worked through `make_call` as the example.
- [MCP Tool Call Example](https://callmcp.ai/tutorials/mcp-tool-call-example): One full `tools/call` end to end — request, response, polling for status, fetching a transcript, and all four documented failure-mode shapes.
- [MCP for AI Phone Agents](https://callmcp.ai/ai-phone-agent-mcp): Guide for agent builders — inbound vs. outbound calling, call logs/transcripts, human handoff via `transfer_enabled`, and writing outcomes back to a CRM with `upsert_lead`.
- [Safety & Compliance](https://callmcp.ai/safety): What's enforced server-side (the `agent.patch` broker: idempotency, authority envelopes, approval queue, versioned config) vs. MCP client annotations, plus a TCPA outline — AI/recording disclosure, one-party vs. two-party consent, do-not-call suppression, quiet-hours — with real gaps named explicitly.

## Tools (51 total via `tools/list` — grouped here for scanability, not the exhaustive schema; call `tools/list` or fetch `.well-known/mcp.json` for the full JSON Schema of every tool)
- **Calls (5)** — `make_call`, `check_call_status`, `list_recent_calls`, `get_transcript`, `get_call_recording`
- **Numbers (5)** — `search_available_numbers`, `buy_number`, `attach_number`, `detach_number`, `list_numbers`
- **SMS & conversations (4)** — `send_sms`, `list_sms_messages`, `list_conversations`, `get_conversation`
- **Voicemail (1)** — `list_voicemails`
- **Webhooks (3)** — `set_webhook`, `get_webhook`, `delete_webhook` (16 event types; deliveries are HMAC-SHA256 signed, `idempotency_key` per event)
- **Agent config (governed writes) (8)** — `update_agent_config`, `configure_agent_business_rules`, `request_kaicalls_update`, `configure_staff_alerts`, `configure_textable_links`, `list_config_versions`, `get_change_history`, `rollback_config` (rollback is itself approval-gated, same broker — see Safety)
- **Leads & CRM (3)** — `upsert_lead`, `list_leads`, `get_lead`
- **Agents & voices (5)** — `list_agents`, `create_agent`, `list_voices`, `get_business_info`, `get_operational_settings`
- **Knowledge base (2)** — `list_knowledge`, `upsert_knowledge`
- **Product catalog (2)** — `list_products`, `upsert_product`
- **Campaigns & analytics (6)** — `list_campaigns`, `create_campaign`, `list_workflow_templates`, `get_analytics`, `get_usage`, `get_balance`
- **Billing & subscription history (3)** — `list_subscription_history`, `list_overage_charges`, `list_rightsize_recommendations`
- **Observability (2)** — `list_observability_events`, `list_tool_execution_logs`
- **Evals (2)** — `list_evals`, `run_eval`

## Scopes (OAuth2-style, checked per tool on `tools/call`)
`calls:read`, `calls:write`, `numbers:read`, `numbers:write`, `sms:read`, `sms:write`, `agents:read`, `agents:write`, `leads:write`, `webhooks:read`, `webhooks:write`, `evals:read`, `evals:write`. `request_kaicalls_update` resolves its required scope per-intent at call time rather than a single fixed scope; `get_usage`/`get_balance` accept any authenticated key with no scope check (matching their REST equivalents).

## What's real vs. not yet built
- Real, live in production: the MCP endpoint, both `.well-known` discovery documents, the `/api/v1/signup` x402 flow, all 51 tools, webhook delivery, the config-write approval broker (idempotency + authority + versioned snapshots), and the `buy_number` approval gate.
- Not yet built: no server-side approval gate in front of `make_call` (annotation-only — `buy_number` now has one, see above), no National DNC Registry lookup, no public sandbox/demo number. Full list: `/safety`.

## Contact
- Website: https://callmcp.ai
- Built on the same telephony stack as KaiCalls (https://www.kaicalls.com) — production infrastructure already carrying live business phone lines, not a new/unproven backend.