Docs › Build

AI & MCP

Handset is built to be operated by agents: an MCP server that gives any AI a phone system, a skill that teaches coding agents the integration patterns, and machine-readable docs.

The MCP server

One config line gives Claude Code, Claude Desktop, or Cursor the whole surface — send texts, place calls, read live transcripts and AI summaries, buy numbers, provision tenants:

terminal

# Claude Code
claude mcp add handset -e HANDSET_API_KEY=hs_test_… -- npx -y @handset/mcp

mcp.json

{
  "handset": {
    "command": "npx",
    "args": ["-y", "@handset/mcp"],
    "env": { "HANDSET_API_KEY": "hs_test_…" }
  }
}

Fifteen curated tools: send_message, make_call, get_transcript, start_transcription, search_numbers, buy_number, create_tenant, and the rest of what an agent actually reaches for.

Safe by default

Use your test-mode key: the agent gets free instant numbers and simulated calls — it can provision, text, and dial with zero real-world consequence, which makes it the fastest way to feel the API. The server refuses live keys unless HANDSET_ALLOW_LIVE=1 is set, and outward-facing tools carry confirm-first warnings in their descriptions.

The agent skill

A companion skill teaches coding agents the patterns that make Handset integrations correct — test-mode-first, the tenant model, idempotent sends, webhooks vs realtime, magic numbers:

terminal

mkdir -p .claude/skills/handset
npx -y @handset/mcp --skill > .claude/skills/handset/SKILL.md

Machine-readable docs

Point an agent at /llms.txt for the index, or /llms-full.txt for every guide page as plain text in one file.

Building a voice agent?

MCP tools cover control; for the audio itself, attach a media stream — fork or bidirectional raw call audio over WebSockets — and drive your own speech loop. The realtime event stream carries transcripts and lifecycle the moment they happen.

PreviousRealtime events NextTypeScript SDK