ClearTalk MCP
Connect your AI assistant — what it can do with ClearTalk, how the MCP server works, and how to connect from Claude, Cursor, VS Code, and other MCP clients.
ClearTalk runs an MCP server — MCP (Model Context Protocol) is the open standard AI assistants use to work with outside systems. Connect it and your assistant stops being a chatbot that talks about ClearTalk and becomes one that can work in it: build and test agents, search contacts, read transcripts, book appointments, and — with your confirmation — place a single call or text.
What it can do
The toolset is deliberately curated — not a machine translation of the whole API, but the workflows an assistant is actually good at:
| Capability | Tools |
|---|---|
| Build agents — create an agent of any type, write or refine its Agent Instructions, pick a voice, attach knowledge | list_agents, get_agent, create_agent, update_agent, list_voices, create_knowledge_base, list_knowledge_bases |
| Design conversation flows — list Pathways, generate a complete one from a written description, or start an empty one and author it | list_pathways, create_pathway, generate_pathway, get_pathway_generation |
| Edit and publish a Pathway — read the working graph, save changes as a new version, browse the version history, and publish when the tests pass | get_pathway_graph, save_pathway_graph, list_pathway_versions, get_pathway_version, promote_pathway |
| Test before going live — create simulated-caller scenarios, run them (credits, but no real calls), read scored transcripts, check the publish gate | create_test_scenario, generate_test_scenario_from_call, run_test, run_all_tests, get_test_run, get_test_batch, list_test_scenarios, get_promotion_readiness |
| Work with your data — contacts, campaigns, and the record of every conversation with transcript, recording, and Result | search_contacts, get_contact, create_contact, update_contact, list_campaigns, get_campaign, list_conversations, get_conversation |
| Appointments — check availability and book against your real calendar | list_event_types, get_available_slots, book_appointment, list_bookings |
| Reach out — one person at a time — place one real call or start one real text conversation | trigger_call, send_text |
| Stay compliant — check both do-not-contact lists before outreach, block a number the moment someone asks, pause a campaign | check_do_not_contact, add_to_do_not_contact, pause_campaign |
Things people actually ask their assistant once it's connected:
- "Build me an outbound agent that books solar consultations — then test it against an angry caller and a voicemail before we try it for real."
- "Why did yesterday's calls go badly? Read the failed transcripts and fix the agent's instructions."
- "Did anyone ask us to stop contacting them this week? Make sure they're on the do-not-call list."
- "Find the call with Jane Doe from Tuesday and summarize how it ended."
It can
- Create and edit agents, Pathways, tests, contacts, and bookings
- Run simulated test conversations that spend credits but dial no one
- Place ONE real call or text — after asking you first
- Add numbers to the do-not-contact lists
It never can
- Start a campaign or dial a contact list — bulk outreach stays in the dashboard
- Remove anyone from a do-not-contact list
- Delete anything
- Touch billing, credits, or account settings
How it works
The server is a thin, deliberately forgetful layer in front of the same API this documentation describes. It holds no data and no credentials of its own — your API key, sent with every request, is the only thing that identifies and authorizes the connection.
- 1
You ask your assistant for something
"Test my solar agent against an impatient caller."
- 2
The assistant picks a tool and calls the MCP server
Your API key rides along on the request, straight from your client's settings.
- 3
The server forwards the call to the ClearTalk API with your key
Nothing is stored — the key and the request die together. Permissions, organization boundaries, and rate limits are enforced by the API, exactly as for any other API caller.
- 4
The result comes back as plain data
Scored transcripts, contact records, booking confirmations — the assistant reads them and answers you.
Three consequences worth knowing:
- The key is the whole relationship. The assistant reaches exactly what the key's organization owns — nothing else — and revoking the key (Integrations → API access) kills the connection instantly.
- Nothing persists between requests. There's no session on our side, no stored conversation, no cached data.
- The server also teaches. It ships built-in instructions every assistant reads before its first tool call: how ClearTalk's pieces fit together, the test-first workflow, and the rule that live actions need your explicit go-ahead every time.
Connect it
You need two things: the server address, and an API key (create one under Integrations → API access).
https://mcp.cleartalk.ai/mcpClaude Code
One command:
claude mcp add --transport http cleartalk https://mcp.cleartalk.ai/mcp \
--header "Authorization: Bearer ct_your_key"Claude Desktop
Settings → Developer → Edit Config, then add under mcpServers:
{
"mcpServers": {
"cleartalk": {
"type": "http",
"url": "https://mcp.cleartalk.ai/mcp",
"headers": { "Authorization": "Bearer ct_your_key" }
}
}
}Cursor
Settings → MCP → Add new server, or add to .cursor/mcp.json in your project:
{
"mcpServers": {
"cleartalk": {
"url": "https://mcp.cleartalk.ai/mcp",
"headers": { "Authorization": "Bearer ct_your_key" }
}
}
}VS Code (Copilot agent mode)
Add .vscode/mcp.json to your workspace:
{
"servers": {
"cleartalk": {
"type": "http",
"url": "https://mcp.cleartalk.ai/mcp",
"headers": { "Authorization": "Bearer ct_your_key" }
}
}
}Any other MCP client
The server speaks standard streamable HTTP. Point the client at the URL above and have it send either header on every request — that's the entire contract:
Authorization: Bearer ct_your_key
— or —
X-API-Key: ct_your_keyclaude.ai and ChatGPT in the browser
Browser-based connectors (claude.ai's custom connectors, ChatGPT's) require an OAuth sign-in flow this server doesn't offer yet, so they can't connect today. The connection works everywhere a key header can be configured: Claude Code, Claude Desktop, Cursor, VS Code, and other desktop/CLI MCP clients. OAuth support is planned.
The key has full access to its organization — treat the client config file it lives in like a password. Team members should each use their own named key, so access can be revoked per person.
The skill (recommended for Claude)
Alongside the connection, we publish a skill — a guide your assistant reads that teaches it the craft, not just the tools: how to structure Agent Instructions that perform, how to design test scenarios that catch real failures, and how to read scores. With the skill installed, "build me an appointment-setting agent" produces markedly better results.
Download the three files, keeping the folder layout:
Place them in a cleartalk folder inside your skills directory — for Claude Code, .claude/skills/cleartalk/ in your project (keep the references subfolder).
That's it. The assistant loads the skill automatically whenever ClearTalk work comes up.
Safety model
- Live actions announce themselves. The tools that touch the real world — placing a call, sending a text, booking a meeting — are marked as live operations, and the assistant is instructed to state what will happen and get your confirmation before each one, every time.
- Test runs are simulated. Agent testing spends credits but never places a call — that's the point: agents earn their way to real conversations.
- The dangerous surface doesn't exist. No campaign start, no batch dialing, no do-not-contact removals, no deletes — those aren't restricted, they're absent, and an automated check keeps them absent.
- Everything is attributable. Actions taken through the connection are ordinary API calls under the key's organization, visible in the same places any API activity is.