Agent Discovery (AID + MCP)

Discover the endpoint

Install the AID CLI and run discover:

bash
npm install -g @agentcommunity/aid-doctor
aid-doctor discover kaicalls.com

# Output:
# ✓ Found AID record
# Protocol: mcp
# URI: https://api.kaicalls.com/mcp
# Auth: bearer
# Docs: https://www.kaicalls.com/docs

Or fetch the .well-known fallback directly:

bash
curl https://www.kaicalls.com/.well-known/aid.json

MCP endpoint

Endpoint

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

Discovery alias

https://api.kaicalls.com/mcp

Protocol

Model Context Protocol (MCP)

Auth

Bearer token — use your KaiCalls API key (kc_live_...; a kc_test_ sandbox prefix is on the roadmap but not yet available)

Content-Type

application/json

Create an API key from the dashboard. Grant the scopes each tool requires (calls:read, calls:write, agents:read).

HTTP routes

Three top-level paths. The first is public; the other two require a Bearer API key.

• POST /api/mcp/initialize — MCP handshake. Public.
• POST /api/mcp/tools/list — list available tools. Requires Bearer.
• POST /api/mcp/tools/call — execute a tool. Requires Bearer plus the tool's scope.

A JSON-RPC 2.0 handler is also available at POST /api/mcp for clients that speak the full MCP JSON-RPC spec.

Tool definitions advertise outputSchema. Tool results include readable content plus structured structuredContent for IDs, counts, pagination metadata, status fields, and error details. Clients should use structured fields instead of parsing the text block. Authenticated tool lists are scope-filtered; public discovery documents show the full inventory and required scopes.

Available tools

Recommended first read-only flow: call get_business_info, then list_agents, then list_recent_calls. Use returned IDs with check_call_status and get_transcript. Only call make_call after explicit user confirmation.

make_call

Initiate an outbound call. Scope: calls:write.

Arguments:

• agent_id (string, required) — must belong to the key's business
• to (string, required) — E.164 phone number
• context (string, optional) — free-form script hint
• name (string, optional) — caller name
• first_message (string, optional) — override greeting
• lead_id (string, optional) — existing lead to associate

bash
curl -X POST https://www.kaicalls.com/api/mcp/tools/call \
  -H "Authorization: Bearer kc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "make_call",
    "arguments": {
      "agent_id": "abc123",
      "to": "+19085551234",
      "context": "Follow up on inquiry"
    }
  }'

check_call_status

Get status of a call. Scope: calls:read.

bash
curl -X POST https://www.kaicalls.com/api/mcp/tools/call \
  -H "Authorization: Bearer kc_live_..." \
  -d '{"name":"check_call_status","arguments":{"call_id":"<uuid>"}}'

get_transcript

Get transcript + summary of a completed call. Scope: calls:read.

bash
curl -X POST https://www.kaicalls.com/api/mcp/tools/call \
  -H "Authorization: Bearer kc_live_..." \
  -d '{"name":"get_transcript","arguments":{"call_id":"<uuid>"}}'

list_recent_calls

List recent calls for the authenticated business. Scope: calls:read.

bash
curl -X POST https://www.kaicalls.com/api/mcp/tools/call \
  -H "Authorization: Bearer kc_live_..." \
  -d '{"name":"list_recent_calls","arguments":{"limit":10,"offset":0}}'

For pagination, call again with offset=structuredContent.next_offset when structuredContent.has_more is true.

list_agents

List KaiCalls agents available to the key. Scope: agents:read.

bash
curl -X POST https://www.kaicalls.com/api/mcp/tools/call \
  -H "Authorization: Bearer kc_live_..." \
  -d '{"name":"list_agents","arguments":{"limit":50,"offset":0}}'

get_business_info

Basic metadata about businesses the key can access. Scope: agents:read.

bash
curl -X POST https://www.kaicalls.com/api/mcp/tools/call \
  -H "Authorization: Bearer kc_live_..." \
  -d '{"name":"get_business_info","arguments":{}}'

Add to an AI client

To connect this MCP server to Claude, ChatGPT, Cursor, VS Code / GitHub Copilot, Windsurf, Mistral, Grok, or Perplexity, see the AI Connectors install guide.

Security & multi-tenancy

• HTTPS-only. HTTP requests are rejected at the edge.
• Every tool call is scoped to the business(es) the API key belongs to. make_call cannot use an agent from another tenant.
• Invalid, revoked, or expired keys return 401.
• Missing scopes return 403.
• Rate limits apply the same way as the rest of the /api/v1 surface.

DNS TXT record (reference)

For transparency, the AID discovery record published at _agent.kaicalls.com:

dns
_agent.kaicalls.com. 300 IN TXT "v=aid1;p=mcp;u=https://api.kaicalls.com/mcp;a=bearer;d=https://www.kaicalls.com/docs"

Verify with dig _agent.kaicalls.com TXT.