KaiCalls

Official51 toolsLive

by KaiCalls

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

KaiCalls MCP Server (com.kaicalls/kaicalls)

The KaiCalls MCP Server exposes an “AI phone secretary” as a remote Model Context Protocol server. It can place calls, read call transcripts, and list calls, along with related information such as agents and call statistics. It is provided as a public connector definition for the hosted service, including endpoint details and a tool catalog.

🛠️ Key Features

Place calls
Read transcripts
List calls
Retrieve agents and stats
Tool catalog with documented endpoint and authentication

🚀 Use Cases

Business phone answering flows, including overflow handling
Lead intake and appointment scheduling
Outbound campaigns and missed-call alerts
Voicemail, texts, and outbound call follow-ups

⚡ Developer Benefits

MCP clients can access KaiCalls capabilities via a documented tool catalog
Public connector definition supports integration with MCP gateways and clients

⚠️ Limitations

Hosted service is referenced; detailed behavior is limited to the documented connector/tool catalog excerpt

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. Pass an idempotency_key to make the request safely retryable: a replay with the same key returns the original call instead of dialing again, and the same key with different arguments is rejected.

Parameters7

agent_id	string	required	KaiCalls agent ID to use for the call
to	string	required	Phone number to call (E.164 format, e.g. +19085551234)
name	string	optional	Caller/lead name (optional)
context	string	optional	Call context or reason (optional)
first_message	string	optional	Override the agent greeting message (optional)
lead_id	string	optional	Existing lead ID to associate (optional)
idempotency_key	string	optional	Client-chosen key that makes this call exactly-once: retries with the same key never place a second call (optional but recommended)

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "KaiCalls agent ID to use for the call"
    },
    "to": {
      "type": "string",
      "description": "Phone number to call (E.164 format, e.g. +19085551234)"
    },
    "name": {
      "type": "string",
      "description": "Caller/lead name (optional)"
    },
    "context": {
      "type": "string",
      "description": "Call context or reason (optional)"
    },
    "first_message": {
      "type": "string",
      "description": "Override the agent greeting message (optional)"
    },
    "lead_id": {
      "type": "string",
      "description": "Existing lead ID to associate (optional)"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Client-chosen key that makes this call exactly-once: retries with the same key never place a second call (optional but recommended)"
    }
  },
  "required": [
    "agent_id",
    "to"
  ]
}

check_call_status

Check the status of a call by its ID

Parameters1

call_id

string

required

The call ID to check

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The call ID to check"
    }
  },
  "required": [
    "call_id"
  ]
}

list_recent_calls

List recent calls for the authenticated business

Parameters4

limit	integer	optional	Max results to return (default 20, max 100)
offset	integer	optional	Zero-based pagination offset (default 0)
agent_id	string	optional	Filter by agent ID (optional)
status	string	optional	Filter by status (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 20, max 100)"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based pagination offset (default 0)"
    },
    "agent_id": {
      "type": "string",
      "description": "Filter by agent ID (optional)"
    },
    "status": {
      "type": "string",
      "description": "Filter by status (optional)"
    }
  }
}

get_transcript

Get the transcript and summary of a completed call

Parameters1

call_id

string

required

The call ID to get the transcript for

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The call ID to get the transcript for"
    }
  },
  "required": [
    "call_id"
  ]
}

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.

Parameters1

call_id

string

required

The KaiCalls call ID to get the recording for

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The KaiCalls call ID to get the recording for"
    }
  },
  "required": [
    "call_id"
  ]
}

list_agents

List KaiCalls agents available to the authenticated account

Parameters3

business_id	string	optional	Business ID to filter by (optional, must be accessible)
limit	integer	optional	Max results to return (default 50, max 100)
offset	integer	optional	Zero-based pagination offset (default 0)

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID to filter by (optional, must be accessible)"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 50, max 100)"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based pagination offset (default 0)"
    }
  }
}

get_business_info

Get business information, agent count, and recent call stats

Parameters1

business_id

string

optional

Business ID (optional, defaults to first accessible business)

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "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.

Parameters1

business_id

string

optional

Business ID (optional, defaults to first accessible business)

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "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.

Parameters7

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

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token has exactly one accessible business)"
    },
    "notification_phone": {
      "type": [
        "string",
        "array"
      ],
      "items": {
        "type": "string"
      },
      "description": "Comma-separated string or array of staff phone numbers that receive SMS escalation alerts."
    },
    "notification_email": {
      "type": [
        "string",
        "array"
      ],
      "items": {
        "type": "string"
      },
      "description": "Comma-separated string or array of staff email addresses that receive escalation emails."
    },
    "sms_notifications": {
      "type": "boolean",
      "description": "Enable or disable SMS staff alerts for this business."
    },
    "email_notifications": {
      "type": "boolean",
      "description": "Enable or disable email staff alerts for this business."
    },
    "escalation_rules": {
      "type": "array",
      "description": "Post-call escalation rules evaluated against completed transcripts. Each rule is { id?, when, then, enabled? }. v1 action then includes text_owner.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "when": {
            "type": "string",
            "description": "Natural-language trigger, e.g. \"Caller needs a same-day callback from the recovery room\"."
          },
          "then": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Action keys. v1 supports text_owner."
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "when"
        ]
      }
    },
    "dry_run": {
      "type": "boolean",
      "description": "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.

Parameters3

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

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token has exactly one accessible business)"
    },
    "links": {
      "type": "array",
      "description": "Links to create/update by link_key. New links require label and destination_url. Existing links can be deactivated with is_active=false.",
      "items": {
        "type": "object",
        "properties": {
          "link_key": {
            "type": "string",
            "description": "Snake_case key the agent/tool uses, e.g. recovery_directions."
          },
          "label": {
            "type": "string",
            "description": "Human label for the link."
          },
          "destination_url": {
            "type": "string",
            "description": "HTTPS destination URL. kaicalls.com destinations are rejected."
          },
          "is_active": {
            "type": "boolean",
            "description": "Whether this link can be sent."
          }
        }
      }
    },
    "dry_run": {
      "type": "boolean",
      "description": "Validate and show create/update plan without writing."
    }
  },
  "required": [
    "links"
  ]
}

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.

Parameters11

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

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "KaiCalls agent ID to update"
    },
    "business_id": {
      "type": "string",
      "description": "Business ID. Required when the agent has multiple accessible assignments."
    },
    "section_title": {
      "type": "string",
      "description": "Prompt section heading to replace/append. Default: Operational handoff rules."
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Plain-language operational rules to insert as bullets, e.g. callback capture, sister-location boundaries, urgent alert handling."
    },
    "mode": {
      "type": "string",
      "description": "replace (default) or append."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Required for writes. Reuse the same key when retrying the same proposed prompt change."
    },
    "actor": {
      "type": "object",
      "description": "Who is asking: { type: agent|human|system|integration, id, display_name }."
    },
    "authority": {
      "type": "object",
      "description": "Human-grade authority for live prompt changes: { mode: human_confirmed|dashboard_session|system_policy, confirmed_by, confirmed_at, confirmation_ref }."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Validate and show the prompt patch metadata without writing."
    },
    "queue_for_approval": {
      "type": "boolean",
      "description": "When authority is missing, create a pending dashboard approval instead of returning needs_approval."
    },
    "source_ref": {
      "type": "string",
      "description": "External source reference, such as a support ticket or Claude conversation ID."
    }
  },
  "required": [
    "agent_id",
    "rules"
  ]
}

list_leads

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

Parameters5

limit	integer	optional	Max results to return (default 50, max 100)
offset	integer	optional	Zero-based pagination offset (default 0)
status	string	optional	Filter by lead status (optional)
source	string	optional	Filter by lead source (optional)
agent_id	string	optional	Filter by agent ID (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 50, max 100)"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based pagination offset (default 0)"
    },
    "status": {
      "type": "string",
      "description": "Filter by lead status (optional)"
    },
    "source": {
      "type": "string",
      "description": "Filter by lead source (optional)"
    },
    "agent_id": {
      "type": "string",
      "description": "Filter by agent ID (optional)"
    }
  }
}

get_lead

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

Parameters1

lead_id

string

required

The lead ID to fetch

Raw schema

{
  "type": "object",
  "properties": {
    "lead_id": {
      "type": "string",
      "description": "The lead ID to fetch"
    }
  },
  "required": [
    "lead_id"
  ]
}

list_voicemails

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

Parameters2

limit	integer	optional	Max results to return (default 20, max 100)
offset	integer	optional	Zero-based pagination offset (default 0)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 20, max 100)"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based pagination offset (default 0)"
    }
  }
}

list_sms_messages

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

Parameters4

limit	integer	optional	Max results to return (default 50, max 100)
offset	integer	optional	Zero-based pagination offset (default 0)
conversation_id	string	optional	Filter by conversation ID (optional)
direction	string	optional	Filter by direction: inbound or outbound (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 50, max 100)"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based pagination offset (default 0)"
    },
    "conversation_id": {
      "type": "string",
      "description": "Filter by conversation ID (optional)"
    },
    "direction": {
      "type": "string",
      "description": "Filter by direction: inbound or outbound (optional)"
    }
  }
}

list_campaigns

List outbound call campaigns for the authenticated business.

Parameters3

limit	integer	optional	Max results to return (default 25, max 100)
offset	integer	optional	Zero-based pagination offset (default 0)
status	string	optional	Filter by campaign status (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 25, max 100)"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based pagination offset (default 0)"
    },
    "status": {
      "type": "string",
      "description": "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.

Parameters7

business_id	string	optional	Business ID (required only when the token can access multiple businesses).
name	string	required	Campaign name.
description	string	optional	Optional campaign description.
cadence_config	object	required	Cadence configuration. { template: standard\|aggressive\|nurture\|custom, attempts: number }.
lead_ids	array	optional	Lead IDs to enroll in the campaign (optional at create time).
launch	boolean	optional	When true, launch the campaign immediately after creating it.
agent_id	string	optional	Agent ID to place the calls. Required when launch is true.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (required only when the token can access multiple businesses)."
    },
    "name": {
      "type": "string",
      "description": "Campaign name."
    },
    "description": {
      "type": "string",
      "description": "Optional campaign description."
    },
    "cadence_config": {
      "type": "object",
      "description": "Cadence configuration. { template: standard|aggressive|nurture|custom, attempts: number }.",
      "properties": {
        "template": {
          "type": "string"
        },
        "attempts": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10
        }
      }
    },
    "lead_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Lead IDs to enroll in the campaign (optional at create time)."
    },
    "launch": {
      "type": "boolean",
      "description": "When true, launch the campaign immediately after creating it."
    },
    "agent_id": {
      "type": "string",
      "description": "Agent ID to place the calls. Required when launch is true."
    }
  },
  "required": [
    "name",
    "cadence_config"
  ]
}

list_workflow_templates

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. Call this before create_campaign so an external agent can trigger a multi-step sequence with launch=true instead of guessing the cadence_config shape blind. Static catalog — no per-business state.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

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.

Parameters1

days

integer

optional

Lookback window in days (default 30, max 90)

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90,
      "description": "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.

Parameters3

business_id	string	optional	Business ID. Required for create when the API key can access multiple businesses.
lead	object	optional	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.
updates	array	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID. Required for create when the API key can access multiple businesses."
    },
    "lead": {
      "type": "object",
      "description": "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."
    },
    "updates": {
      "type": "array",
      "description": "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.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Lead ID to update."
          }
        },
        "required": [
          "id"
        ]
      }
    }
  }
}

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.

Parameters5

from_agent_id	string	required	Agent ID whose phone line the text is sent from.
to	string	required	Recipient phone number in E.164 format (e.g. +18135551234).
message	string	required	Text message body.
lead_id	string	optional	Optional lead ID to link and honor the lead's automation-pause state.
idempotency_key	string	optional	Optional caller-supplied key. A replay with the same key returns the original send outcome instead of sending again — use it when retrying after an uncertain response.

Raw schema

{
  "type": "object",
  "properties": {
    "from_agent_id": {
      "type": "string",
      "description": "Agent ID whose phone line the text is sent from."
    },
    "to": {
      "type": "string",
      "description": "Recipient phone number in E.164 format (e.g. +18135551234)."
    },
    "message": {
      "type": "string",
      "description": "Text message body."
    },
    "lead_id": {
      "type": "string",
      "description": "Optional lead ID to link and honor the lead's automation-pause state."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional caller-supplied key. A replay with the same key returns the original send outcome instead of sending again — use it when retrying after an uncertain response."
    }
  },
  "required": [
    "from_agent_id",
    "to",
    "message"
  ]
}

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). Every write here is reversible: inspect what changed with get_change_history or list_config_versions, then undo it with rollback_config. 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.

Parameters18

agent_id	string	required	KaiCalls agent ID to update.
business_id	string	optional	Business ID. Required when the agent has multiple accessible assignments.
first_message	string	optional	Spoken greeting / first message callers hear.
inbound_prompt	string	optional	Full inbound system prompt that drives the agent.
outbound_prompt	string	optional	Outbound (campaign) system prompt.
sms_prompt	string	optional	SMS reply prompt.
name	string	optional	Agent display name.
voice	object	optional	Voice selection: { provider, voiceId }.
model	object	optional	Language model selection: { provider, model, temperature }.
max_duration	integer	optional	Maximum call duration in seconds.
transfer_enabled	boolean	optional	Enable/disable live call transfer.
transfer_phone_number	string	optional	Number to transfer qualified calls to.
idempotency_key	string	optional	Required for writes. Reuse the same key when retrying the same change.
actor	object	optional	Who is asking: { type: agent\|human\|system\|integration, id, display_name }.
authority	object	optional	Human-grade authority for live changes: { mode: human_confirmed\|dashboard_session\|system_policy, confirmed_by, confirmed_at, confirmation_ref }.
dry_run	boolean	optional	Validate and summarize the change without writing.
queue_for_approval	boolean	optional	When authority is missing, create a pending dashboard approval instead of returning needs_approval.
source_ref	string	optional	External source reference, such as a support ticket or conversation ID.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "KaiCalls agent ID to update."
    },
    "business_id": {
      "type": "string",
      "description": "Business ID. Required when the agent has multiple accessible assignments."
    },
    "first_message": {
      "type": "string",
      "description": "Spoken greeting / first message callers hear."
    },
    "inbound_prompt": {
      "type": "string",
      "description": "Full inbound system prompt that drives the agent."
    },
    "outbound_prompt": {
      "type": "string",
      "description": "Outbound (campaign) system prompt."
    },
    "sms_prompt": {
      "type": "string",
      "description": "SMS reply prompt."
    },
    "name": {
      "type": "string",
      "description": "Agent display name."
    },
    "voice": {
      "type": "object",
      "description": "Voice selection: { provider, voiceId }."
    },
    "model": {
      "type": "object",
      "description": "Language model selection: { provider, model, temperature }."
    },
    "max_duration": {
      "type": "integer",
      "description": "Maximum call duration in seconds."
    },
    "transfer_enabled": {
      "type": "boolean",
      "description": "Enable/disable live call transfer."
    },
    "transfer_phone_number": {
      "type": "string",
      "description": "Number to transfer qualified calls to."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Required for writes. Reuse the same key when retrying the same change."
    },
    "actor": {
      "type": "object",
      "description": "Who is asking: { type: agent|human|system|integration, id, display_name }."
    },
    "authority": {
      "type": "object",
      "description": "Human-grade authority for live changes: { mode: human_confirmed|dashboard_session|system_policy, confirmed_by, confirmed_at, confirmation_ref }."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Validate and summarize the change without writing."
    },
    "queue_for_approval": {
      "type": "boolean",
      "description": "When authority is missing, create a pending dashboard approval instead of returning needs_approval."
    },
    "source_ref": {
      "type": "string",
      "description": "External source reference, such as a support ticket or conversation ID."
    }
  },
  "required": [
    "agent_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, numbers.purchase, agent.config.rollback. 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.

Parameters12

intent	string	required	Update intent: phone.emergency_address.set, transcripts.sink.configure, agent.patch, numbers.purchase, or agent.config.rollback
business_id	string	optional	Business ID. Required when the API key can access multiple businesses.
target	object	optional	Target identifiers, e.g. { phone_number } for E911 or { agent_id } for agent.patch.
payload	object	optional	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_key	string	optional	Required for any mutating request. Repeating a key returns the original outcome instead of re-running provider side effects.
actor	object	optional	Who is asking: { type: agent\|human\|system\|integration, id, display_name }.
authority	object	optional	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_run	boolean	optional	Validate tenant, scope, schema, authority, and policy without executing.
queue_for_approval	boolean	optional	When authority is missing, create a pending dashboard approval instead of returning needs_approval.
reason	string	optional	Required when changing raw vapi_config; recorded in the durable audit.
source_ref	string	optional	External source reference, such as a Discord message or automation run ID.
requester	object	optional	Optional legacy requester metadata for audit trails (prefer actor).

Raw schema

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string",
      "description": "Update intent: phone.emergency_address.set, transcripts.sink.configure, agent.patch, numbers.purchase, or agent.config.rollback"
    },
    "business_id": {
      "type": "string",
      "description": "Business ID. Required when the API key can access multiple businesses."
    },
    "target": {
      "type": "object",
      "description": "Target identifiers, e.g. { phone_number } for E911 or { agent_id } for agent.patch."
    },
    "payload": {
      "type": "object",
      "description": "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_key": {
      "type": "string",
      "description": "Required for any mutating request. Repeating a key returns the original outcome instead of re-running provider side effects."
    },
    "actor": {
      "type": "object",
      "description": "Who is asking: { type: agent|human|system|integration, id, display_name }."
    },
    "authority": {
      "type": "object",
      "description": "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_run": {
      "type": "boolean",
      "description": "Validate tenant, scope, schema, authority, and policy without executing."
    },
    "queue_for_approval": {
      "type": "boolean",
      "description": "When authority is missing, create a pending dashboard approval instead of returning needs_approval."
    },
    "reason": {
      "type": "string",
      "description": "Required when changing raw vapi_config; recorded in the durable audit."
    },
    "source_ref": {
      "type": "string",
      "description": "External source reference, such as a Discord message or automation run ID."
    },
    "requester": {
      "type": "object",
      "description": "Optional legacy requester metadata for audit trails (prefer actor)."
    }
  },
  "required": [
    "intent"
  ]
}

get_usage

List recent API usage events (endpoint, method, status code, cost) for the caller's account. Mirrors GET /api/v1/usage.

Parameters3

start	string	optional	ISO date/time lower bound (optional).
end	string	optional	ISO date/time upper bound (optional).
limit	integer	optional	Max results to return (default 100, max 500).

Raw schema

{
  "type": "object",
  "properties": {
    "start": {
      "type": "string",
      "description": "ISO date/time lower bound (optional)."
    },
    "end": {
      "type": "string",
      "description": "ISO date/time upper bound (optional)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Max results to return (default 100, max 500)."
    }
  }
}

get_balance

Get per-business minutes-used and subscription status across every business the caller can access. Mirrors GET /api/v1/balance.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

list_numbers

List phone numbers owned by the accessible business(es), with capability and compliance flags. Mirrors GET /api/v1/numbers.

Parameters1

business_id

string

optional

Business ID to filter by (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID to filter by (optional)."
    }
  }
}

list_conversations

List SMS conversation threads (counterparty timeline metadata) for the authenticated business, most recent first. Mirrors GET /api/v1/sms/conversations.

Parameters1

limit

integer

optional

Max results to return (default 50, max 100).

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 50, max 100)."
    }
  }
}

get_conversation

Get a single SMS conversation thread by ID. Mirrors GET /api/v1/sms/conversations?id=.

Parameters1

conversation_id

string

required

The conversation ID to fetch.

Raw schema

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "The conversation ID to fetch."
    }
  },
  "required": [
    "conversation_id"
  ]
}

get_webhook

List the configured outbound webhook(s) for a business, including supported event types. Mirrors GET /api/v1/webhooks.

Parameters1

business_id

string

optional

Business ID (optional only when the token can access exactly one business).

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    }
  }
}

set_webhook

Create or update a business outbound webhook (URL + subscribed events). Returns a webhook secret on first creation only. Mirrors POST /api/v1/webhooks.

Parameters6

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
webhook_url	string	required	HTTPS/HTTP destination URL for event delivery.
id	string	optional	Existing webhook ID to update (omit to create new).
events	array	optional	Event types to subscribe to (see get_webhook for the supported list).
description	string	optional	Human label for this webhook.
is_active	boolean	optional	Enable or disable delivery.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "webhook_url": {
      "type": "string",
      "description": "HTTPS/HTTP destination URL for event delivery."
    },
    "id": {
      "type": "string",
      "description": "Existing webhook ID to update (omit to create new)."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Event types to subscribe to (see get_webhook for the supported list)."
    },
    "description": {
      "type": "string",
      "description": "Human label for this webhook."
    },
    "is_active": {
      "type": "boolean",
      "description": "Enable or disable delivery."
    }
  },
  "required": [
    "webhook_url"
  ]
}

delete_webhook

Remove a business outbound webhook by ID. Mirrors DELETE /api/v1/webhooks.

Parameters2

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
id	string	required	Webhook ID to remove.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "id": {
      "type": "string",
      "description": "Webhook ID to remove."
    }
  },
  "required": [
    "id"
  ]
}

list_evals

List canned mock-conversation eval scenarios for an agent (or all accessible agents). Mirrors GET /api/v1/evals.

Parameters1

agent_id

string

optional

Filter by agent ID (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Filter by agent ID (optional)."
    }
  }
}

run_eval

Run a single eval scenario (eval_id) or every scenario for an agent (agent_id) against its live Vapi assistant and grade the result. Bills Vapi compute. Mirrors POST /api/v1/evals/run.

Parameters4

eval_id	string	optional	Run a single eval scenario by ID.
agent_id	string	optional	Run every eval scenario for this agent.
wait	boolean	optional	Block until the run completes (default true).
max_wait_ms	integer	optional	Per-run wait cap in ms when wait is true (default 60000, max 110000).

Raw schema

{
  "type": "object",
  "properties": {
    "eval_id": {
      "type": "string",
      "description": "Run a single eval scenario by ID."
    },
    "agent_id": {
      "type": "string",
      "description": "Run every eval scenario for this agent."
    },
    "wait": {
      "type": "boolean",
      "description": "Block until the run completes (default true)."
    },
    "max_wait_ms": {
      "type": "integer",
      "description": "Per-run wait cap in ms when wait is true (default 60000, max 110000)."
    }
  }
}

list_voices

List the curated, credential-free voice catalog (id, display name, accent, language, gender, sample URL) used to configure agent voices. Mirrors GET /api/v1/voices.

Parameters3

language	string	optional	Filter by language label, e.g. English or Spanish.
provider	string	optional	Filter by provider, e.g. vapi, 11labs, or azure.
gender	string	optional	Filter by gender: male or female.

Raw schema

{
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "Filter by language label, e.g. English or Spanish."
    },
    "provider": {
      "type": "string",
      "description": "Filter by provider, e.g. vapi, 11labs, or azure."
    },
    "gender": {
      "type": "string",
      "description": "Filter by gender: male or female."
    }
  }
}

create_agent

Create a new KaiCalls voice agent (Vapi assistant + KaiCalls records) with a system prompt, greeting, voice, and model. Mirrors POST /api/v1/agents. Every subsequent mutation to this agent is versioned (assistant_config_versions) and reversible via rollback_config — inspect history with get_change_history / list_config_versions. Compliance: KaiCalls automatically applies state-aware AI-disclosure and consent handling to every agent it provisions, and flags high-risk business categories for extra review.

Parameters8

business_id	string	required	Business ID to create the agent under.
name	string	required	Agent display name.
system_prompt	string	required	The agent's inbound system prompt / instructions.
first_message	string	optional	Spoken greeting (optional).
voice	object	optional	Raw voice selection: { provider, voiceId } (optional).
voice_catalog_id	string	optional	Preferred: a curated catalog id from list_voices (optional).
model	object	optional	Language model selection: { provider, model, temperature } (optional).
metadata	object	optional	Extra KaiCalls metadata to store (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID to create the agent under."
    },
    "name": {
      "type": "string",
      "description": "Agent display name."
    },
    "system_prompt": {
      "type": "string",
      "description": "The agent's inbound system prompt / instructions."
    },
    "first_message": {
      "type": "string",
      "description": "Spoken greeting (optional)."
    },
    "voice": {
      "type": "object",
      "description": "Raw voice selection: { provider, voiceId } (optional)."
    },
    "voice_catalog_id": {
      "type": "string",
      "description": "Preferred: a curated catalog id from list_voices (optional)."
    },
    "model": {
      "type": "object",
      "description": "Language model selection: { provider, model, temperature } (optional)."
    },
    "metadata": {
      "type": "object",
      "description": "Extra KaiCalls metadata to store (optional)."
    }
  },
  "required": [
    "business_id",
    "name",
    "system_prompt"
  ]
}

attach_number

Assign a phone number already in the KaiCalls registry pool to a business (and optionally route it directly to an agent). Does NOT purchase a new number — use search_available_numbers + buy_number for that. Mirrors POST /api/v1/phone-numbers.

Parameters3

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
phone_number	string	required	E.164 phone number already in the registry.
agent_id	string	optional	Agent ID to route this number to directly (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "phone_number": {
      "type": "string",
      "description": "E.164 phone number already in the registry."
    },
    "agent_id": {
      "type": "string",
      "description": "Agent ID to route this number to directly (optional)."
    }
  },
  "required": [
    "phone_number"
  ]
}

detach_number

Release a phone number from a business back to the unassigned registry pool. Mirrors DELETE /api/v1/phone-numbers.

Parameters2

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
phone_number	string	required	E.164 phone number to release.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "phone_number": {
      "type": "string",
      "description": "E.164 phone number to release."
    }
  },
  "required": [
    "phone_number"
  ]
}

search_available_numbers

Search the carrier for phone numbers available to purchase (real-time Twilio inventory lookup). Mirrors GET /api/v1/phone-numbers/search.

Parameters3

area_code	string	optional	Preferred area code (optional).
country	string	optional	Two-letter country code (default US).
limit	integer	optional	Max results to return (default 10, max 20).

Raw schema

{
  "type": "object",
  "properties": {
    "area_code": {
      "type": "string",
      "description": "Preferred area code (optional)."
    },
    "country": {
      "type": "string",
      "description": "Two-letter country code (default US)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Max results to return (default 10, max 20)."
    }
  }
}

buy_number

Purchase a real phone number from the carrier and register it to a business. This spends real money — the number is billed by the carrier immediately, so the purchase is APPROVAL-GATED: without human-grade authority (an authority envelope with mode human_confirmed, or a dashboard approval) the tool executes nothing and returns a pending_approval record the business owner approves or denies from the dashboard — relay the returned confirmation text to them. Agent-initiated purchases never run unattended. Does not auto-attach an agent; call attach_number afterward to route it. Mirrors POST /api/v1/phone-numbers/purchase via the numbers.purchase update intent. Compliance: KaiCalls automatically applies state-aware AI-disclosure and consent handling to numbers it provisions, and flags high-risk business categories for extra review.

Parameters10

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
phone_number	string	required	The exact E.164 phone number to purchase, as returned by search_available_numbers.
agent_id	string	optional	Agent ID to route this number to directly once purchased (optional; requires the number to also be voice-runtime-imported, which is not guaranteed at purchase time — prefer a follow-up attach_number call).
idempotency_key	string	optional	Stable key for the purchase request; repeating it returns the original outcome. Defaults to a key derived from the phone number — pass your own to retry a previously failed purchase.
actor	object	optional	Who is asking: { type: agent\|human\|system\|integration, id, display_name }.
authority	object	optional	How the purchase was authorized: { mode, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields; anything weaker returns pending_approval.
queue_for_approval	boolean	optional	When authority is insufficient, create a durable dashboard approval (default true). Set false to get needs_approval and retry yourself with the same idempotency_key once a human confirms.
dry_run	boolean	optional	Validate tenant, scope, and policy without buying anything.
reason	string	optional	Optional reason recorded in the durable audit.
source_ref	string	optional	External source reference, such as a ticket or automation run ID.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "phone_number": {
      "type": "string",
      "description": "The exact E.164 phone number to purchase, as returned by search_available_numbers."
    },
    "agent_id": {
      "type": "string",
      "description": "Agent ID to route this number to directly once purchased (optional; requires the number to also be voice-runtime-imported, which is not guaranteed at purchase time — prefer a follow-up attach_number call)."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Stable key for the purchase request; repeating it returns the original outcome. Defaults to a key derived from the phone number — pass your own to retry a previously failed purchase."
    },
    "actor": {
      "type": "object",
      "description": "Who is asking: { type: agent|human|system|integration, id, display_name }."
    },
    "authority": {
      "type": "object",
      "description": "How the purchase was authorized: { mode, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields; anything weaker returns pending_approval."
    },
    "queue_for_approval": {
      "type": "boolean",
      "description": "When authority is insufficient, create a durable dashboard approval (default true). Set false to get needs_approval and retry yourself with the same idempotency_key once a human confirms."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Validate tenant, scope, and policy without buying anything."
    },
    "reason": {
      "type": "string",
      "description": "Optional reason recorded in the durable audit."
    },
    "source_ref": {
      "type": "string",
      "description": "External source reference, such as a ticket or automation run ID."
    }
  },
  "required": [
    "phone_number"
  ]
}

list_knowledge

List agent knowledge base entries for a business. Mirrors GET /api/v1/knowledge.

Parameters3

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
category	string	optional	Filter by category (optional).
query	string	optional	Free-text search over title/content (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "category": {
      "type": "string",
      "description": "Filter by category (optional)."
    },
    "query": {
      "type": "string",
      "description": "Free-text search over title/content (optional)."
    }
  }
}

upsert_knowledge

Create a new agent knowledge base entry, or update one when `id` is provided. Mirrors POST /api/v1/knowledge. Creating requires title, content, and content_type.

Parameters7

id	string	optional	Knowledge item ID to update (omit to create).
business_id	string	optional	Business ID. Required for create when the token can access multiple businesses.
title	string	optional
content	string	optional
content_type	string	optional
category	string	optional
tags	array	optional

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Knowledge item ID to update (omit to create)."
    },
    "business_id": {
      "type": "string",
      "description": "Business ID. Required for create when the token can access multiple businesses."
    },
    "title": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

list_products

List a business's agent product catalog. Mirrors GET /api/v1/products.

Parameters4

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
category	string	optional	Filter by category (optional).
query	string	optional	Free-text search over name/description (optional).
inventory	boolean	optional	Include current inventory quantity per product (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "category": {
      "type": "string",
      "description": "Filter by category (optional)."
    },
    "query": {
      "type": "string",
      "description": "Free-text search over name/description (optional)."
    },
    "inventory": {
      "type": "boolean",
      "description": "Include current inventory quantity per product (optional)."
    }
  }
}

upsert_product

Create a new product row, or update one when `id` is provided. Mirrors POST /api/v1/products. Creating requires name and business_id. Pass `quantity` to set/update inventory.

Parameters9

id	string	optional	Product ID to update (omit to create).
business_id	string	optional	Business ID. Required for create when the token can access multiple businesses.
name	string	optional
description	string	optional
category	string	optional
price	number	optional
sku	string	optional
attributes	object	optional
quantity	number	optional	Inventory quantity to set (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Product ID to update (omit to create)."
    },
    "business_id": {
      "type": "string",
      "description": "Business ID. Required for create when the token can access multiple businesses."
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "price": {
      "type": "number"
    },
    "sku": {
      "type": "string"
    },
    "attributes": {
      "type": "object"
    },
    "quantity": {
      "type": "number",
      "description": "Inventory quantity to set (optional)."
    }
  }
}

list_config_versions

List an agent's hashed, redacted assistant config version history (rollback lineage included). Pass `version` to fetch one version's full redacted config_snapshot instead of the list. Mirrors GET /api/v1/agents/versions.

Parameters3

agent_id	string	required	Agent ID (required).
version	integer	optional	Fetch a single version by its per-agent version_number, including its redacted config_snapshot (optional; omit to list).
limit	integer	optional	Max versions to return when listing (optional, default 50, max 100).

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent ID (required)."
    },
    "version": {
      "type": "integer",
      "description": "Fetch a single version by its per-agent version_number, including its redacted config_snapshot (optional; omit to list)."
    },
    "limit": {
      "type": "integer",
      "description": "Max versions to return when listing (optional, default 50, max 100)."
    }
  },
  "required": [
    "agent_id"
  ]
}

get_change_history

List an agent's recent config-change audit trail (change_type, change_source, old/new value, timestamp) from admin_change_history — the same record the admin_get_change_history voice tool reads over the phone. Every mutation KaiCalls makes to an agent (via update_agent_config, configure_agent_business_rules, the admin call-in secretary, or the dashboard) is logged here and reversible with rollback_config.

Parameters2

agent_id	string	required	Agent ID to fetch change history for.
limit	integer	optional	Max results to return (default 20, max 100).

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent ID to fetch change history for."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results to return (default 20, max 100)."
    }
  },
  "required": [
    "agent_id"
  ]
}

rollback_config

Roll an agent's deployed voice configuration back to a prior assistant_config_versions snapshot — restoring greeting, voice, prompt, and scalar model params (never secrets/credentials) onto the live agent. This OVERWRITES the live deployed config, so it is APPROVAL-GATED: without human-grade authority (an authority envelope with mode human_confirmed, or a dashboard approval) the tool executes nothing and returns a pending_approval record the business owner approves or denies from the dashboard — relay the returned confirmation text to them. Agent-initiated rollbacks never run unattended. Wraps the same version-restore logic as POST /api/v1/agents/rollback and the admin_rollback_change voice tool, via the agent.config.rollback update intent. Discover a target with list_config_versions or get_change_history. Every executed rollback records a new config version; to repeat a rollback that already executed, pass a fresh idempotency_key.

Parameters11

agent_id	string	required	Agent ID to roll back.
business_id	string	optional	Business ID (optional only when the token can access exactly one business).
version_number	integer	optional	Target assistant_config_versions.version_number to restore. One of version_number/version_id is required.
version_id	string	optional	Target assistant_config_versions row id to restore. One of version_number/version_id is required.
reason	string	optional	Optional human-readable reason recorded in the audit trail.
idempotency_key	string	optional	Stable key for the rollback request; repeating it returns the original outcome. Defaults to a key derived from agent + version — pass a fresh key to repeat a rollback that already executed.
actor	object	optional	Who is asking: { type: agent\|human\|system\|integration, id, display_name }.
authority	object	optional	How the rollback was authorized: { mode, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields; anything weaker returns pending_approval.
queue_for_approval	boolean	optional	When authority is insufficient, create a durable dashboard approval (default true). Set false to get needs_approval and retry yourself with the same idempotency_key once a human confirms.
dry_run	boolean	optional	Validate tenant, scope, and policy without touching the live config.
source_ref	string	optional	External source reference, such as a ticket or automation run ID.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "description": "Agent ID to roll back."
    },
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "version_number": {
      "type": "integer",
      "description": "Target assistant_config_versions.version_number to restore. One of version_number/version_id is required."
    },
    "version_id": {
      "type": "string",
      "description": "Target assistant_config_versions row id to restore. One of version_number/version_id is required."
    },
    "reason": {
      "type": "string",
      "description": "Optional human-readable reason recorded in the audit trail."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Stable key for the rollback request; repeating it returns the original outcome. Defaults to a key derived from agent + version — pass a fresh key to repeat a rollback that already executed."
    },
    "actor": {
      "type": "object",
      "description": "Who is asking: { type: agent|human|system|integration, id, display_name }."
    },
    "authority": {
      "type": "object",
      "description": "How the rollback was authorized: { mode, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields; anything weaker returns pending_approval."
    },
    "queue_for_approval": {
      "type": "boolean",
      "description": "When authority is insufficient, create a durable dashboard approval (default true). Set false to get needs_approval and retry yourself with the same idempotency_key once a human confirms."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Validate tenant, scope, and policy without touching the live config."
    },
    "source_ref": {
      "type": "string",
      "description": "External source reference, such as a ticket or automation run ID."
    }
  },
  "required": [
    "agent_id"
  ]
}

list_observability_events

List a business-scoped timeline of compact call-runtime events and redacted integration-delivery attempts. Mirrors GET /api/v1/observability-events and uses bounded keyset pagination.

Parameters17

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
source	string	optional	Event stream to read (default: all).
from	string	optional
to	string	optional
limit	integer	optional
cursor	string	optional	Opaque next_cursor returned by the previous page.
event_type	string	optional	Runtime-event filter.
severity	string	optional	Runtime-event filter.
call_id	string	optional	Runtime-event call UUID filter.
conversation_id	string	optional	Runtime-event filter.
correlation_id	string	optional	Runtime-event filter.
provider	string	optional	Integration-delivery filter.
outcome	string	optional	Integration-delivery filter.
operation	string	optional	Integration-delivery filter.
object_type	string	optional	Integration-delivery filter.
object_id	string	optional	Integration-delivery filter.
connection_id	string	optional	Integration connection UUID filter.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "source": {
      "type": "string",
      "enum": [
        "all",
        "runtime",
        "delivery"
      ],
      "description": "Event stream to read (default: all)."
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "cursor": {
      "type": "string",
      "description": "Opaque next_cursor returned by the previous page."
    },
    "event_type": {
      "type": "string",
      "description": "Runtime-event filter."
    },
    "severity": {
      "type": "string",
      "enum": [
        "info",
        "warning",
        "error"
      ],
      "description": "Runtime-event filter."
    },
    "call_id": {
      "type": "string",
      "description": "Runtime-event call UUID filter."
    },
    "conversation_id": {
      "type": "string",
      "description": "Runtime-event filter."
    },
    "correlation_id": {
      "type": "string",
      "description": "Runtime-event filter."
    },
    "provider": {
      "type": "string",
      "description": "Integration-delivery filter."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "success",
        "failure"
      ],
      "description": "Integration-delivery filter."
    },
    "operation": {
      "type": "string",
      "description": "Integration-delivery filter."
    },
    "object_type": {
      "type": "string",
      "description": "Integration-delivery filter."
    },
    "object_id": {
      "type": "string",
      "description": "Integration-delivery filter."
    },
    "connection_id": {
      "type": "string",
      "description": "Integration connection UUID filter."
    }
  },
  "additionalProperties": false
}

list_tool_execution_logs

List per-call Vapi tool execution traces from vapi_tool_execution_logs — outcome, latency, timeout, and a redacted result preview for each routed tool call. Mirrors GET /api/v1/tool-execution-logs. Answers "did this tool call actually work".

Parameters8

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
call_id	string	optional	Vapi call/conversation id filter.
tool_call_id	string	optional	Exact tool_call_id filter.
tool_name	string	optional	Tool name filter (e.g. send_sms).
outcome_status	string	optional	Outcome envelope status filter (e.g. success, needs_clarification, unavailable, queued, retryable_delay, hard_failure).
from	string	optional
to	string	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "call_id": {
      "type": "string",
      "description": "Vapi call/conversation id filter."
    },
    "tool_call_id": {
      "type": "string",
      "description": "Exact tool_call_id filter."
    },
    "tool_name": {
      "type": "string",
      "description": "Tool name filter (e.g. send_sms)."
    },
    "outcome_status": {
      "type": "string",
      "description": "Outcome envelope status filter (e.g. success, needs_clarification, unavailable, queued, retryable_delay, hard_failure)."
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "additionalProperties": false
}

list_subscription_history

List plan/price change history from subscription_change_history — the billing analogue of admin_change_history, written from the Stripe webhook and the right-size apply job. Mirrors GET /api/v1/subscription-history.

Parameters6

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
change_type	string	optional
source	string	optional	e.g. stripe_webhook, rightsize_apply_job.
from	string	optional
to	string	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "change_type": {
      "type": "string",
      "enum": [
        "plan_change",
        "created",
        "canceled",
        "reactivated",
        "rightsize"
      ]
    },
    "source": {
      "type": "string",
      "description": "e.g. stripe_webhook, rightsize_apply_job."
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "additionalProperties": false
}

list_overage_charges

List the idempotent overage-minutes ledger from billing_overage_charges (legacy per-minute-overage tiers only — 2026 plans carry no overage). GET /v1/balance/get_balance only returns an aggregate; this returns the underlying per-period ledger rows. Mirrors GET /api/v1/overage-charges.

Parameters5

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
status	string	optional
from	string	optional
to	string	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "synced",
        "skipped",
        "error"
      ]
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "additionalProperties": false
}

list_rightsize_recommendations

List per-period auto-right-size decisions from plan_rightsize_recommendations, including the dry_run -> notified -> (kept | applied | superseded) lifecycle. Answers "is this business about to get right-sized". Mirrors GET /api/v1/rightsize-recommendations.

Parameters6

business_id	string	optional	Business ID (optional only when the token can access exactly one business).
status	string	optional
action	string	optional
from	string	optional
to	string	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Business ID (optional only when the token can access exactly one business)."
    },
    "status": {
      "type": "string",
      "enum": [
        "dry_run",
        "notified",
        "kept",
        "applied",
        "superseded"
      ]
    },
    "action": {
      "type": "string",
      "enum": [
        "none",
        "upgrade",
        "downgrade",
        "handoff_custom"
      ]
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "additionalProperties": false
}

README.md21 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
Setup endpoint	`https://www.kaicalls.com/api/mcp/acquisition` (setup-only subset for first-time buyers)
Tools	69 on the account endpoint (39 read-only, 30 write/setup); 37 on the setup endpoint
Homepage	callmcp.ai
Provider	KaiCalls · connor@kaicalls.com
License	MIT (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, 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

The account endpoint exposes 69 tools: 39 read-only and 30 write/setup. Every tool carries MCP safety annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). The setup endpoint (/api/mcp/acquisition) exposes the 37 tools marked ✅ 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 and server-card.json. In-depth notes for the core tools are in docs/tools.md. The live tools/list response returns each tool's input schema.

Read-only tools (39)

Tool	Scope	Setup surface	What it does
`get_extra_number_status`	`numbers:read`	✅	Read an owner-authorized extra-number request.
`get_setup_recovery_status`	`numbers:read`	✅	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`	✅	List the KaiCalls agents on the authenticated account.
`get_business_info`	`agents:read`	✅	Read back what a business already has: profile details, how many agents are configured, and recent call volume.
`get_operational_settings`	`agents:read`	✅	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`	✅	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`	✅	List recent API usage events (endpoint, method, status code, cost) for the caller's account.
`list_plans`	`billing:read`	✅	Read the canonical public KaiCalls plan catalog, monthly USD prices and allowances.
`get_checkout_status`	`billing:read`	✅	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`	✅	List phone numbers assigned to the accessible business(es), with capability and compliance flags.
`get_phone_flow`	`numbers:read`	✅	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`	✅	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`	✅	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`	✅	Search the carrier for phone numbers available to purchase (real-time Twilio inventory lookup).
`list_knowledge`	`knowledge:read`	✅	List agent knowledge base entries for a business.
`list_products`	`products:read`		List a business's agent product catalog.
`list_config_versions`	`agents:read`	✅	List an agent's hashed, redacted assistant config version history (rollback lineage included).
`get_change_history`	`agents:read`	✅	List an agent's recent config-change audit trail (change_type, change_source, old/new value, timestamp) from admin_change_history — the same record the admin_get_change_history voice tool reads over the phone.
`list_observability_events`	`events:read`		List a business-scoped timeline of compact call-runtime events and redacted integration-delivery attempts.
`list_tool_execution_logs`	`events:read`		List per-call Vapi tool execution traces from vapi_tool_execution_logs — outcome, latency, timeout, and a redacted result preview for each routed tool call.
`list_subscription_history`	`billing:read`		List plan/price change history from subscription_change_history — the billing analogue of admin_change_history, written from the Stripe webhook and the right-size apply job.
`list_overage_charges`	`billing:read`		List the idempotent overage-minutes ledger from billing_overage_charges (legacy per-minute-overage tiers only — 2026 plans carry no overage).
`list_rightsize_recommendations`	`billing:read`		List per-period auto-right-size decisions from plan_rightsize_recommendations, including the dry_run -> notified -> (kept \| applied \| superseded) lifecycle.

Write and setup tools (30)

Tool	Scope	Setup surface	Hints	What it does
`request_extra_number`	`billing:write`	✅	idempotent · open-world	Reserve an exact pool number and request an owner-only browser review of its recurring extra-line price.
`retry_setup`	`numbers:write`	✅	destructive · idempotent	Reconcile database pointers for an existing imported signup phone reservation.
`make_call`	`calls:write`	✅	destructive · open-world	Initiate an outbound voice preview via a KaiCalls AI agent.
`configure_staff_alerts`	`agents:write`	✅	destructive · idempotent	Save business-owned staff alert recipients and post-call escalation rules.
`confirm_notification_destination`	`agents:write`	✅	destructive · idempotent	APPROVAL-GATED. Save the owner-approved SMS or email destination for the exact active activation session.
`retry_activation_notification`	`agents:write`	✅	destructive · idempotent	APPROVAL-GATED. Retry only the current terminal or time-eligible activation notification channel for the exact active session.
`choose_customer_route`	`numbers:write`	✅	destructive · idempotent	APPROVAL-GATED. After setup proof is complete, save forwarding, published_number, both, or testing.
`configure_textable_links`	`agents:write`	✅	destructive · idempotent	Create or repair the business_links entries used by the send_link/send_sms tools.
`configure_agent_business_rules`	`agents:write`	✅	destructive · idempotent · open-world	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.
`create_campaign`	`calls:write`		destructive · open-world	Create an outbound call campaign (cadence + lead batch) and optionally launch it immediately.
`upsert_lead`	`leads:write`		destructive	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).
`send_sms`	`sms:write`		destructive · open-world	Send an outbound text message from one of your agents' phone lines to a recipient, routed through the governed messaging API.
`update_agent_config`	`agents:write`	✅	destructive · idempotent · open-world	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).
`request_kaicalls_update`	intent-specific		destructive · idempotent · open-world	Ask the KaiCalls on-behalf update broker to perform a scoped, governed mutation.
`create_checkout`	`billing:write`	✅	idempotent · open-world	Create or resume an owner-bound hosted Stripe checkout for a current plan from list_plans.
`update_phone_flow`	`numbers:write`	✅	destructive · idempotent	Replace how calls ring on the business's hosted phone system with a full phone flow: { version: 1, hours: { mode: 'always' \| 'business_hours', afterHours: 'kai' }, ring: { members: [{ kind: 'cell', phone: E.164, label, requirePressOne } \| { kind: 'desk_phone' \| 'user', userId, label }], timeoutSeconds: 5-120 }, overflow: 'kai' }.
`set_up_phone_system`	`numbers:write`	✅	destructive · idempotent · open-world	Turn the business's number into a hosted phone system: Kai is installed as extension 700, the owner's mobile joins a team ring group, and a dial plan rings the team first and hands the call to Kai when nobody picks up.
`add_team_phone`	`numbers:write`	✅	destructive · idempotent · open-world	Add a teammate's (or the owner's) cell to the phone system's team ring group so it rings before Kai answers.
`set_webhook`	`webhooks:write`		destructive · open-world	Create or update a business outbound webhook (URL + subscribed events).
`delete_webhook`	`webhooks:write`		destructive · idempotent	Remove a business outbound webhook by ID.
`run_eval`	`evals:write`		destructive · open-world	Run a single eval scenario (eval_id) or every scenario for an agent (agent_id) against its live Vapi assistant and grade the result.
`create_agent`	`agents:write`	✅	open-world	Create a new KaiCalls agent — the secretary that answers this business’s calls (Vapi assistant + KaiCalls records) — with a system prompt, greeting, voice, and model.
`attach_number`	`numbers:write`	✅	destructive · idempotent · open-world	Assign a phone number already in the KaiCalls registry pool to a business (and optionally route it directly to an agent).
`set_owner_phone`	`agents:write`	✅	destructive · idempotent	Save the owner's own mobile number on the business record so Kai can ring it first and so activation/forwarding follow-ups can reach a human.
`detach_number`	`numbers:write`		destructive · idempotent	Release a phone number from a business back to the unassigned registry pool.
`buy_number`	`numbers:write`	✅	destructive · idempotent · open-world	Request a real phone-number purchase.
`upsert_knowledge`	`knowledge:write`	✅	destructive	Create a new agent knowledge base entry, or update one when `id` is provided.
`upsert_product`	`products:write`		destructive	Create a new product row, or update one when `id` is provided.
`rollback_config`	`agents:write`	✅	destructive · idempotent	Request a rollback to a prior assistant_config_versions snapshot.
`report_issue`	`support:write`		—	Report a problem with your KaiCalls agent, phone number, billing, or account.

Write-tool safety. Tools marked destructive change live business configuration or reach the outside world: make_call places an outbound voice preview, send_sms sends a real text through opt-out, Do-Not-Call and quiet-hours gates, and create_campaign can queue outbound calls. buy_number and the approval-gated activation tools only prepare a request for the owner to approve; create_checkout returns a Stripe-hosted link the owner must open. Prompt changes route through the governed broker, need an idempotency key plus human authority or a queued approval, and every outcome is audited.

Configuration

The server is hosted, so the only configuration is authentication. Pick one:

Setting	Required	How to send it	Notes
OAuth 2.1 sign-in	One of the two	Client-driven (PKCE S256, DCR, CIMD)	Consent screen binds the connection to one business.
KaiCalls API key (`kc_live_...`)	One of the two	`Authorization: Bearer kc_live_...` or `X-KaiCalls-API-Key: kc_live_...`	Generate in the KaiCalls dashboard under Settings → API Keys.

The same choice is declared in server.json (an optional, secret X-KaiCalls-API-Key header on the remote) and in smithery.yaml (an optional kaicallsApiKey config field). Leave the key empty to use OAuth.

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). The registry entry is generated from server.json; the Smithery listing from smithery.yaml.

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

Tools (51)

make_callcheck_call_statuslist_recent_callsget_transcriptget_call_recordinglist_agentsget_business_infoget_operational_settings

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

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

Add to VS Code Add to Cursor

claude_desktop_config.json

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.

KaiCalls MCP Server (com.kaicalls/kaicalls)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

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

list_workflow_templates

get_analytics

upsert_lead

send_sms

update_agent_config

request_kaicalls_update

get_usage

get_balance

list_numbers

list_conversations

get_conversation

get_webhook

set_webhook

delete_webhook

list_evals

run_eval

list_voices

create_agent

attach_number

detach_number

search_available_numbers

buy_number

list_knowledge

upsert_knowledge

list_products

upsert_product

list_config_versions

get_change_history

rollback_config

list_observability_events

list_tool_execution_logs

list_subscription_history

list_overage_charges

list_rightsize_recommendations

KaiCalls MCP Server

Quick Answer

Quick connect

Claude (web & desktop) / ChatGPT

API-key clients / MCP gateways

Cline / remote MCP clients

Tools

Read-only tools (39)

Write and setup tools (30)

Configuration

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

Remote endpoint

Related servers