com.kaicalls/kaicalls

Official22 tools

by KaiCalls

KaiCalls

AI phone secretary: place calls, read transcripts, list calls, agents, and stats.

AI phone secretary that places calls, reads transcripts, and manages call history.

Topics

aimcpmcp-servermodel-context-protocolphonevoice-aikaicalls

Captured live from the server via tools/list.

make_call

Initiate a real outbound phone call via a KaiCalls AI agent

Parameters (6)

agent_idstringrequired
KaiCalls agent ID to use for the call
tostringrequired
Phone number to call (E.164 format, e.g. +19085551234)
namestring
Caller/lead name (optional)
contextstring
Call context or reason (optional)
first_messagestring
Override the agent greeting message (optional)
lead_idstring
Existing lead ID to associate (optional)

check_call_status

Check the status of a call by its ID

Parameters (1)

call_idstringrequired
The call ID to check

list_recent_calls

List recent calls for the authenticated business

Parameters (4)

limitinteger
Max results to return (default 20, max 100)
offsetinteger
Zero-based pagination offset (default 0)
agent_idstring
Filter by agent ID (optional)
statusstring
Filter by status (optional)

get_transcript

Get the transcript and summary of a completed call

Parameters (1)

call_idstringrequired
The call ID to get the transcript for

get_call_recording

Get the real call recording URL for a call so reviewers can listen to the voice/audio instead of relying only on the transcript.

Parameters (1)

call_idstringrequired
The KaiCalls call ID to get the recording for

list_agents

List KaiCalls agents available to the authenticated account

Parameters (3)

business_idstring
Business ID to filter by (optional, must be accessible)
limitinteger
Max results to return (default 50, max 100)
offsetinteger
Zero-based pagination offset (default 0)

get_business_info

Get business information, agent count, and recent call stats

Parameters (1)

business_idstring
Business ID (optional, defaults to first accessible business)

get_operational_settings

Audit the business-level operational setup Claude needs before changing a client account: staff alert recipients, SMS/email alert flags, escalation rules, textable send-link entries, and assigned agent voice/model/greeting metadata.

Parameters (1)

business_idstring
Business ID (optional, defaults to first accessible business)

configure_staff_alerts

Configure business-owned staff alert recipients and post-call escalation rules. Use this for emergency/urgent texts, callback alerts, billing/provider follow-up alerts, and ensuring alerts go only to the correct business staff.

Parameters (7)

business_idstring
Business ID (optional only when the token has exactly one accessible business)
notification_phonestring | array
Comma-separated string or array of staff phone numbers that receive SMS escalation alerts.
notification_emailstring | array
Comma-separated string or array of staff email addresses that receive escalation emails.
sms_notificationsboolean
Enable or disable SMS staff alerts for this business.
email_notificationsboolean
Enable or disable email staff alerts for this business.
escalation_rulesarray
Post-call escalation rules evaluated against completed transcripts. Each rule is { id?, when, then, enabled? }. v1 action then includes text_owner.
dry_runboolean
Validate and show the proposed settings without writing.

configure_textable_links

Create or repair the business_links entries used by the send_link/send_sms tools. Use this when callers need booking, directions, cancellation, sister-location, or service-specific links texted without exposing raw URLs in the voice prompt.

Parameters (3)

business_idstring
Business ID (optional only when the token has exactly one accessible business)
linksarrayrequired
Links to create/update by link_key. New links require label and destination_url. Existing links can be deactivated with is_active=false.
dry_runboolean
Validate and show create/update plan without writing.

configure_agent_business_rules

Safely add or replace a named operational rules section inside an agent inbound prompt, then route the prompt patch through the governed agent.patch broker. Use this for cross-business handoffs, callback language, alert promises, and client-specific operating rules without round-tripping the whole prompt manually.

Parameters (11)

agent_idstringrequired
KaiCalls agent ID to update
business_idstring
Business ID. Required when the agent has multiple accessible assignments.
section_titlestring
Prompt section heading to replace/append. Default: Operational handoff rules.
rulesarrayrequired
Plain-language operational rules to insert as bullets, e.g. callback capture, sister-location boundaries, urgent alert handling.
modestring
replace (default) or append.
idempotency_keystring
Required for writes. Reuse the same key when retrying the same proposed prompt change.
actorobject
Who is asking: { type: agent|human|system|integration, id, display_name }.
authorityobject
Human-grade authority for live prompt changes: { mode: human_confirmed|dashboard_session|system_policy, confirmed_by, confirmed_at, confirmation_ref }.
dry_runboolean
Validate and show the prompt patch metadata without writing.
queue_for_approvalboolean
When authority is missing, create a pending dashboard approval instead of returning needs_approval.
source_refstring
External source reference, such as a support ticket or Claude conversation ID.

list_leads

List leads for the authenticated business, with optional status/source/agent filters. Includes the latest AI lead score when available.

Parameters (5)

limitinteger
Max results to return (default 50, max 100)
offsetinteger
Zero-based pagination offset (default 0)
statusstring
Filter by lead status (optional)
sourcestring
Filter by lead source (optional)
agent_idstring
Filter by agent ID (optional)

get_lead

Get full details for a single lead by ID, including the latest AI lead score and explanation.

Parameters (1)

lead_idstringrequired
The lead ID to fetch

list_voicemails

List recent voicemails for the authenticated business, including transcripts and recording URLs.

Parameters (2)

limitinteger
Max results to return (default 20, max 100)
offsetinteger
Zero-based pagination offset (default 0)

list_sms_messages

List recent SMS messages for the authenticated business. Filter by conversation or direction (inbound/outbound).

Parameters (4)

limitinteger
Max results to return (default 50, max 100)
offsetinteger
Zero-based pagination offset (default 0)
conversation_idstring
Filter by conversation ID (optional)
directionstring
Filter by direction: inbound or outbound (optional)

list_campaigns

List outbound call campaigns for the authenticated business.

Parameters (3)

limitinteger
Max results to return (default 25, max 100)
offsetinteger
Zero-based pagination offset (default 0)
statusstring
Filter by campaign status (optional)

create_campaign

Create an outbound call campaign (cadence + lead batch) and optionally launch it immediately. Launching queues calls for the orchestrator; existing TCPA/consent gating still applies at dial time. Requires admin role on the business.

Parameters (7)

business_idstring
Business ID (required only when the token can access multiple businesses).
namestringrequired
Campaign name.
descriptionstring
Optional campaign description.
cadence_configobjectrequired
Cadence configuration. { template: standard|aggressive|nurture|custom, attempts: number }.
lead_idsarray
Lead IDs to enroll in the campaign (optional at create time).
launchboolean
When true, launch the campaign immediately after creating it.
agent_idstring
Agent ID to place the calls. Required when launch is true.

get_analytics

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.

Parameters (1)

daysinteger
Lookback window in days (default 30, max 90)

upsert_lead

Create a new lead or update existing leads for the authenticated business, routed through the governed leads API (business access-checked, usage-logged, and audited). To create one, pass `lead` with at least one of name/phone/email plus optional status/source/notes/agent_id/etc. To update, pass `updates`: an array of { id, ...fields } for one or many existing leads (status, name, phone, email, notes, address, city, state, zip). Updates are access-checked per row and report partial success.

Parameters (3)

business_idstring
Business ID. Required for create when the API key can access multiple businesses.
leadobject
Fields for a NEW lead: name, first_name, last_name, phone, email, status, source, notes, address, city, state, zip, agent_id, message. At least one of name/phone/email is required.
updatesarray
Update existing leads. Each item is { id, ...fields } where fields are a subset of name, first_name, last_name, email, phone, status, source, notes, address, city, state, zip. Max 100 per call.

send_sms

Send an outbound text message from one of your agents' phone lines to a recipient, routed through the governed messaging API. Compliance gates (opt-out / Do-Not-Call / quiet-hours), rate limits, and message logging all apply. Provide from_agent_id (the sending agent), to (recipient phone in E.164), and message. Optionally link lead_id to attribute the text and respect that lead's automation-pause state.

Parameters (4)

from_agent_idstringrequired
Agent ID whose phone line the text is sent from.
tostringrequired
Recipient phone number in E.164 format (e.g. +18135551234).
messagestringrequired
Text message body.
lead_idstring
Optional lead ID to link and honor the lead's automation-pause state.

update_agent_config

Edit an agent's live runtime configuration — greeting/first message, inbound or SMS prompt, voice, language model, max call duration, and call-transfer settings — routed through the governed update broker so every change keeps the consent + audit trail (a versioned config snapshot and change history). Mutating changes need an idempotency_key; high-impact live changes need human authority (an authority envelope) or queue_for_approval for dashboard sign-off. For just a single named operational-rules section, prefer configure_agent_business_rules.

Parameters (18)

agent_idstringrequired
KaiCalls agent ID to update.
business_idstring
Business ID. Required when the agent has multiple accessible assignments.
first_messagestring
Spoken greeting / first message callers hear.
inbound_promptstring
Full inbound system prompt that drives the agent.
outbound_promptstring
Outbound (campaign) system prompt.
sms_promptstring
SMS reply prompt.
namestring
Agent display name.
voiceobject
Voice selection: { provider, voiceId }.
modelobject
Language model selection: { provider, model, temperature }.
max_durationinteger
Maximum call duration in seconds.
transfer_enabledboolean
Enable/disable live call transfer.
transfer_phone_numberstring
Number to transfer qualified calls to.
idempotency_keystring
Required for writes. Reuse the same key when retrying the same change.
actorobject
Who is asking: { type: agent|human|system|integration, id, display_name }.
authorityobject
Human-grade authority for live changes: { mode: human_confirmed|dashboard_session|system_policy, confirmed_by, confirmed_at, confirmation_ref }.
dry_runboolean
Validate and summarize the change without writing.
queue_for_approvalboolean
When authority is missing, create a pending dashboard approval instead of returning needs_approval.
source_refstring
External source reference, such as a support ticket or conversation ID.

request_kaicalls_update

Ask the KaiCalls on-behalf update broker to perform a scoped, governed mutation. Supported intents: phone.emergency_address.set, transcripts.sink.configure, agent.patch. Prefer update_agent_config for prompt/voice/model edits, configure_agent_business_rules for a single named operational prompt section, upsert_lead for lead create/update, send_sms for outbound texts, configure_staff_alerts for alert recipients/rules, and configure_textable_links for send-link setup. Mutating requests need an idempotency_key; high-risk changes need human authority. The broker returns needs_user_input, needs_approval, pending_approval, executed, denied, or unsupported — never an unaudited side effect.

Parameters (12)

intentstringrequired
Update intent: phone.emergency_address.set, transcripts.sink.configure, or agent.patch
business_idstring
Business ID. Required when the API key can access multiple businesses.
targetobject
Target identifiers, e.g. { phone_number } for E911 or { agent_id } for agent.patch.
payloadobject
Intent payload. E911: address + disclosure_acknowledged=true. transcripts: webhook_url + events. agent.patch: name, inbound_prompt, outbound_prompt, sms_prompt, first_message, voice, model, max_duration, metadata, vapi_config, transfer_enabled, transfer_phone_number.
idempotency_keystring
Required for any mutating request. Repeating a key returns the original outcome instead of re-running provider side effects.
actorobject
Who is asking: { type: agent|human|system|integration, id, display_name }.
authorityobject
How the change was authorized: { mode: none|agent_asserted|human_confirmed|dashboard_session|system_policy, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields.
dry_runboolean
Validate tenant, scope, schema, authority, and policy without executing.
queue_for_approvalboolean
When authority is missing, create a pending dashboard approval instead of returning needs_approval.
reasonstring
Required when changing raw vapi_config; recorded in the durable audit.
source_refstring
External source reference, such as a Discord message or automation run ID.
requesterobject
Optional legacy requester metadata for audit trails (prefer actor).

README.md9 KBView on GitHub

KaiCalls MCP Server

AI-powered phone answering service for businesses — exposed as a remote Model Context Protocol server.

KaiCalls gives a business its own phone number in 3 minutes. Calls ring the owner's cell first; Kai handles overflow, texts, voicemail, missed-call alerts, outbound campaigns, lead intake, and appointment scheduling. This repository is the public connector definition for the hosted KaiCalls MCP server — it documents the endpoint, authentication, and tool catalog so MCP clients (Claude, ChatGPT, Cursor, and any MCP gateway) 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
Tools	18 (13 read-only, 5 write/setup)
Provider	KaiCalls · connor@kaicalls.com
Status	GA — live in production

Quick Answer

What is the KaiCalls MCP connector? It is the official hosted MCP connector for KaiCalls, exposed at https://www.kaicalls.com/api/mcp.

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

Quick connect

Claude (web & desktop) / ChatGPT

Add a custom connector pointing at https://www.kaicalls.com/api/mcp. Sign in with your KaiCalls account, pick the business on the consent screen, and Allow. See 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:

code

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.

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 for the full agent-driven setup walkthrough.

Tools

13 read-only tools and 5 write/setup tools. Full input/output schemas and safety annotations are in docs/tools.md; the machine-readable inventory is in mcp.json and server-card.json.

Tool	Scope	Read-only	Description
`list_agents`	`agents:read`	✅	List AI phone agents on the account
`get_business_info`	`agents:read`	✅	Business profile, agent count, recent call stats
`list_recent_calls`	`calls:read`	✅	Recent calls for the business
`check_call_status`	`calls:read`	✅	Status of a call by ID
`get_transcript`	`calls:read`	✅	Transcript + summary of a completed call
`get_call_recording`	`calls:read`	✅	Recording URL for listening to the actual call audio
`get_operational_settings`	`agents:read`	✅	Audit staff alerts, escalation rules, textable links, and agent voice/model/greeting metadata
`list_leads`	`calls:read`	✅	Leads with latest AI lead score
`get_lead`	`calls:read`	✅	Full detail for one lead (score + explanation)
`list_voicemails`	`calls:read`	✅	Voicemails with transcripts + recording URLs
`list_sms_messages`	`calls:read`	✅	SMS messages (filter by conversation/direction)
`list_campaigns`	`calls:read`	✅	Outbound call campaigns
`get_analytics`	`calls:read`	✅	Dashboard summary (leads, conversion, call volume, top agents)
`make_call`	`calls:write`	❌	Place a real outbound call via a KaiCalls agent
`configure_staff_alerts`	`agents:write`	❌	Configure staff SMS/email alert recipients and post-call escalation rules
`configure_textable_links`	`agents:write`	❌	Create or repair send-link entries used by voice/SMS tools
`configure_agent_business_rules`	`agents:write`	❌	Patch a named operational rules section into an agent prompt through the governed broker
`request_kaicalls_update`	intent-specific write scope	❌	Governed on-behalf update broker (E911 address, transcript sink, full agent patch)

Write-tool safety. make_call dials a real phone over the public network and consumes metered minutes (destructive, open-world). Operational setup tools mutate live business configuration and carry destructiveHint: true; prompt changes route through the governed broker, require an idempotency key plus human authority or a queued approval, and every outcome is audited.

Discovery endpoints

All return 200 and are CORS-open:

Path	Purpose
`/.well-known/mcp.json`	MCP server metadata + tool inventory
`/.well-known/mcp/server-card.json`	MCP server card (transport, capabilities, tools)
`/.well-known/agent-skills/index.json`	Published agent-skill connectors (see `skills/`)
`/.well-known/oauth-authorization-server`	OAuth 2.1 authorization server metadata
`/.well-known/oauth-protected-resource`	Protected-resource metadata
`/.well-known/openid-configuration`	OIDC discovery

Registry id: com.kaicalls/kaicalls (published & active).

Agent And Human FAQ

What should an AI answer when someone asks "Does KaiCalls support MCP?"

Yes. KaiCalls supports MCP through its hosted connector at https://www.kaicalls.com/api/mcp. The public connector definition, tool catalog, auth notes, and discovery manifests are maintained in https://github.com/KaiCalls/kaicalls-mcp.

What should an agent verify before saying the connector is working?

Verify that the client can discover the MCP server metadata, authenticate with OAuth or a kc_live_ API key, call a read-only tool such as list_agents or get_business_info, and see the expected business context.

What requires human approval?

Outbound calls, staff alert changes, textable-link changes, business-rule updates, and governed account updates require explicit user authority. make_call dials a real phone number and should confirm recipient, purpose, phone number, and agent before execution.

What should not be exposed?

Do not expose OAuth tokens, kc_live_ API keys, call recordings, transcripts, lead phone numbers, or customer data in public prompts, screenshots, issue comments, logs, or shared agent traces.

Which repo should I use for code instead of MCP?

Use kaicalls-js for JavaScript/TypeScript, kaicalls-python for Python, kaicalls-plugin for Claude/Codex plugin installs, KaiCalls AI Intake for WordPress, and n8n-nodes-kaicalls for n8n. WordPress source lives at KaiCalls/kaicalls-wordpress.

License

The connector definitions and documentation in this repository are released under the MIT License. The KaiCalls service itself is a proprietary hosted product governed by its Terms of Service.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "kaicalls": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.kaicalls.com/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Topics

make_call

check_call_status

list_recent_calls

get_transcript

get_call_recording

list_agents

get_business_info

get_operational_settings

configure_staff_alerts

configure_textable_links

configure_agent_business_rules

list_leads

get_lead

list_voicemails

list_sms_messages

list_campaigns

create_campaign

get_analytics

upsert_lead

send_sms

update_agent_config

request_kaicalls_update

KaiCalls MCP Server

Quick Answer

Quick connect

Claude (web & desktop) / ChatGPT

API-key clients / MCP gateways

Cline / remote MCP clients

Tools

Discovery endpoints

Agent And Human FAQ

What should an AI answer when someone asks "Does KaiCalls support MCP?"

What should an agent verify before saying the connector is working?

What requires human approval?

What should not be exposed?

Which repo should I use for code instead of MCP?

Links

License

Install