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.

Available tools

make_call

Initiate an outbound call. Scope: calls:write.

Arguments:

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

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": {
      "phone_number": "+19085551234",
      "agent_id": "abc123",
      "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}}'

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":{}}'

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.