Developers
Callworthy for AI agents: MCP server and API
Updated November 17, 2026
Short answer: Callworthy has a remote MCP server at https://callworthy.app/mcp and a REST API at https://callworthy.app/api/v1. Both use a bearer token you create under Connect your AI. An agent can brief the receptionist about your businesses so you never type it yourself.
Connect
Claude Code:
claude mcp add --transport http --scope user callworthy https://callworthy.app/mcp \
--header "Authorization: Bearer cw_YOUR_TOKEN"
Any other MCP client: a Streamable HTTP server at the URL above with the header Authorization: Bearer cw_…. Responses are JSON (no event stream), no session is required.
What an agent can do
| Tool | What it does |
|---|---|
get_receptionist | Who the receptionist answers for, her settings, the owner's general notes and call-handling instructions, and every topic she knows. Call this first. |
get_guide | How to write a topic she can use on a live call, and what must stay out. Read before writing. |
upsert_topic | Teach her about one business, product or role, or replace what she knows about it. Reusing a slug overwrites that topic. |
delete_topic | Remove a topic she should no longer know. Ask the owner first. |
update_notes | Replace the general notes about the owner as a person and how their businesses fit together (max 8000 chars). Read the current notes first and keep what is still true. |
update_instructions | Replace the owner's standing rules for handling calls (who always gets through, who never does; max 6000 chars). Only write rules the owner actually gave you. |
update_receptionist | Rename her, change her voice, or change what callers call the owner. |
mark_numbers | Put phone numbers on the always-ring list (skip the questions, ring the owner), block them, or clear them. Use for the owner's important contacts. Up to 200 at a time. |
list_calls | Recent calls she handled, newest first: who, outcome, and her note. show = people (default), spam, or all. |
get_call | One call with its message and full transcript. |
simulate_call | Dry run: give one to four things a caller might say, in order, and see what she replies and decides (keeps talking, rings the owner, takes a message, ends the call). No phone call is made. Use it after writing a topic. |
What an agent cannot do
- See or change the passphrase or the security questions.
- Place calls, including callbacks.
- Switch ring-through, the scam time-waster, or notification settings.
- Read another owner's receptionist. A token belongs to one line.
REST
| Request | Does |
|---|---|
GET /api/v1/receptionist | Settings, notes, instructions and all topics |
PATCH /api/v1/receptionist | Any of notes, instructions, name, voice, callers_call_them |
GET /api/v1/guide | How to write a topic she can use on a call |
GET /api/v1/topics | All topics |
PUT /api/v1/topics/{slug} | Create or replace a topic: title, body |
DELETE /api/v1/topics/{slug} | Remove a topic |
POST /api/v1/numbers | status (always_ring, blocked, cleared) and numbers[] of {number, label} |
GET /api/v1/calls?show=people&limit=25 | Recent calls |
GET /api/v1/calls/{id} | One call with transcript |
POST /api/v1/simulate | caller_says[]: what she would reply and decide, with no phone call |
curl -X PUT https://callworthy.app/api/v1/topics/acme-plumbing \
-H "Authorization: Bearer cw_YOUR_TOKEN" -H "Content-Type: application/json" \
-d '{"title":"Acme Plumbing","body":"Acme Plumbing is a family plumbing company in Springfield…"}'
Limits
- 120 requests a minute per token; 60 dry runs an hour per receptionist.
- 40 topics per receptionist, 4,000 characters each.
- Errors are JSON: 401 for a bad token, 422 with field messages for bad input, 404 for something that is not yours.
Writing for a phone call
The receptionist repeats what she is told to strangers. Give her public facts in plain sentences: what the business is, who calls, what she may say, what is worth interrupting you for, and where else to send people. The get_guide tool returns the full brief, and simulate_call shows how she would handle a caller before a real one finds out.
Voicemail is full. Hire a receptionist.
Callworthy answers the calls you miss, puts the worthy ones through, and keeps spam out. Free during the private beta.