Docs
Open dashboard
Developers

MCP server

Connect an AI assistant to a workspace over the Model Context Protocol and manage it in plain language.

Overview

Inspra runs a remote MCP server: the same operations as the API reference, exposed as tools an AI assistant can call. Connect it once and you can ask an assistant to list agents, read call transcripts, check credits or pause a campaign, without writing a request by hand.

It suits work that is awkward in a dashboard and tedious in code — reading across many calls at once, or checking something quickly mid-task in your editor.

This page is about connecting an assistant to Inspra. It is not about an agent calling out to external tools during a call — that is Tools and custom functions.

What you can do

AreaTools
AgentsList, read, create, update and delete agents.
CallsList calls with filters, read one call in full with its transcript, place an outbound call, and check concurrency.
CampaignsList and read campaigns, list recipients, pause and resume.
ReferenceBrowse the voice catalogue, read a voice, and read the workspace's billing summary.

Seventeen tools in total. Campaign creation and knowledge-base tools are not exposed yet — use the API or the dashboard for those.

How it works

The server is hosted at $DASHBOARD_URL/api/mcp and speaks Streamable HTTP. Here $DASHBOARD_URL is the address you use to open the dashboard, not the API host $API_BASE_URL, so a white-label host works exactly the same way.

It authenticates with a workspace API key sent as a bearer token — the same key the API uses. A key resolves to exactly one workspace, so an assistant can only ever read and change that workspace. There is nothing to scope or misconfigure, and no way for a prompt to reach another workspace's data.

Your assistant fetches the tool list when it starts, which is why a configuration change needs a restart before it takes effect.

Before you start

  • A workspace API key — Configuration → General → API Keys. See API keys.
  • An MCP-capable assistant: Claude Code, Claude Desktop, Cursor, or any client that supports a remote Streamable HTTP server.
  • The server URL: $DASHBOARD_URL/api/mcp.

Connect your client

Pick the tab for your client. Each does the same thing: point the client at $DASHBOARD_URL/api/mcp and send your key as a bearer token. Restart the client afterwards — every one of them reads its tool list at startup.

$DASHBOARD_URL and $API_KEY are placeholders. In a terminal they expand only if you exported them first (export API_KEY=...); in a JSON or TOML file nothing expands them, so paste the real values there, or use the client's own environment-variable option as the Codex and OpenCode tabs do. Keep the key out of files that are checked into source control.

Claude Code. Run this once. --scope user makes the server available in every directory; drop it to limit the server to the current project.

Terminal
claude mcp add --scope user --transport http inspra $DASHBOARD_URL/api/mcp --header "Authorization: Bearer $API_KEY"

Restart Claude Code and run /mcp to confirm it is connected.

Claude Desktop. Open Settings → Developer → Edit Config and add the server inside mcpServers.

claude_desktop_config.json
{
  "mcpServers": {
    "inspra": {
      "type": "http",
      "url": "$DASHBOARD_URL/api/mcp",
      "headers": { "Authorization": "Bearer $API_KEY" }
    }
  }
}

Save the file, then quit the app completely and reopen it. An edit made while the app is running is overwritten when it exits.

What to ask

  • Which of my agents are inactive?
  • How did yesterday's calls go? Anything I should worry about?
  • Show me the transcript of my longest call this week.
  • What is my credit balance, and how much have I used this month?
  • Pause the follow-up campaign.

Reading across calls is where it earns its keep: an assistant can open many transcripts at once and summarise what went wrong, which a dashboard does not do well.

A first read-only request

Ask the assistant Which agents do I have? It calls list_agents and shows one row per agent with the fields the tool returns: id, name, description, provider, whether it is active, direction, whether outbound campaigns are allowed, the voice, model and transcriber providers, the assigned phone number id, the sync status, and the created and updated times. Tags and knowledge documents are not returned. The result is paged (20 per page by default) and carries a pagination block with the page, page size and total.

If instead you see Unauthorized, the key or header is wrong; if no tools appear at all, the client has not been restarted. Both are in the troubleshooting table below.

Actions that cost money

Three tools are marked destructive, so a well-behaved client asks before running them.

ToolWhat it does
place_outbound_callDials a real number and spends credits.
resume_campaignRestarts dialling and spends credits.
delete_agentRemoves an agent. This cannot be undone.

Treat anything a caller said as untrusted text. A transcript can contain instructions aimed at your assistant, so read first and approve writes yourself rather than letting a model act on call content unattended.

Limits

  • Page sizes clamp to 100, with a default of 20.
  • Tool results are capped and truncate with a marker that says how much was dropped. list_calls therefore returns a summary of each call; use get_call for the transcript.
  • Rate limits and credit checks are shared with the API and counted per workspace, not per key — an assistant and a server integration on the same workspace draw on the same allowance: 120 requests per sliding minute by default, counted once per request however many tools it carries. Tool results are capped at 30,000 characters. The figures are under API keys: limits.
  • Requests are stateless: a tool returns as soon as the work is accepted. After resume_campaign, poll get_campaign for progress.

Troubleshooting

SymptomCause and fix
No tools appearThe client only connects at startup. Quit it completely and reopen. In Claude Code, check the scope: a server added without --scope user shows only in the directory where you added it.
UnauthorizedThe key is wrong or revoked, or the header is missing the word Bearer before the key. Create a new key under Configuration → General → API Keys.
Rate limit exceededToo many requests in a short window, counted across everything using that workspace. Wait and retry.
A tool fails but others workRead the message — it carries the same error text the API returns. A workspace out of credits will refuse the tools that spend them while reads keep working.

Go to workspace