Build with an AI assistant (MCP)

Calloop runs an MCP server, so the AI assistant in your editor (Claude Code, Cursor, VS Code, Windsurf, or any other MCP client) can read these docs and work on your Calloop account while it helps you integrate. Ask it something like "integrate my help desk with Calloop" and it can:

• pick your scenario and walk through its steps,
• look up any endpoint, field or event payload,
• write the code in your codebase: backend calls, the webhook receiver, the token endpoint, the agent app,
• set up your tenant, lines, queues and agents,
• check what's missing, and give you a token for a first test call.

The server is at https://api.calloop.net/mcp, next to the API. It uses Streamable HTTP, so there is nothing to install.

Connect

The docs tools work without a key. The account tools need your API key, sent as a header: Authorization: Bearer ck_<slug>_<secret>. Keep the key in an environment variable or a prompt, never in a file you commit.

Claude Code

claude mcp add --transport http calloop https://api.calloop.net/mcp \
  --header "Authorization: Bearer $CALLOOP_API_KEY"

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "calloop": {
      "url": "https://api.calloop.net/mcp",
      "headers": { "Authorization": "Bearer ${env:CALLOOP_API_KEY}" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "inputs": [{ "type": "promptString", "id": "calloop-key", "description": "Calloop API key", "password": true }],
  "servers": {
    "calloop": {
      "type": "http",
      "url": "https://api.calloop.net/mcp",
      "headers": { "Authorization": "Bearer ${input:calloop-key}" }
    }
  }
}

Windsurf (mcp_config.json)

{
  "mcpServers": {
    "calloop": {
      "serverUrl": "https://api.calloop.net/mcp",
      "headers": { "Authorization": "Bearer ${env:CALLOOP_API_KEY}" }
    }
  }
}

For docs only, leave the header out. A client that can't send headers (a hosted chat app's custom connector, for example) gets the docs tools only.

To get started, run the integrate prompt (in Claude Code: /mcp__calloop__integrate), or just describe your product to the assistant.

What it can do

Tool	Needs the key	What it does
docs_contents	no	Every page of these docs, with the names the other tools take (guide/setup, api/queues, events/call.ended, sdks/js…)
docs_read	no	One page in full
docs_search	no	The pages that best match some words (an endpoint, a field, an error code), each with the passage that matches
api_get	yes	GET any Management API path as your account: tenants, lines, queues, calls, events, usage…
api_change	yes	PUT, POST, PATCH or DELETE a Management API path: create and change your setup, place an outbound call, delete. This changes your real account
integration_check	yes	Checks your account against the go-live checklist: webhook and failed deliveries, signing keys, push, and for each tenant its lines (where each line's calls go), agents, queue members and recent calls. It lists what's done, what's missing and what to do next
agent_test_token	yes	Signs a short-lived agent token (1–60 minutes, 15 by default) for one agent of one of your tenants, so you can try the SDK or your app before your backend signs tokens

The integrate prompt takes an optional product (what you're building) and gives the assistant the plan: read the guide and pick a scenario, follow its steps, write the code, check the account, then run through what's left before going live.

Your key and what the assistant can do with it

• The assistant acts as your backend. Every account tool goes through the Management API with your key: the same tenant scoping, validation, errors and idempotency as a direct call. It reaches only your own consumer's data, and nothing outside /v1.
• It can't use up your backend's limit. Calls through the assistant count toward your consumer's 1200 requests a minute, and they also have their own cap of 300 a minute per key. Past that cap, a tool says to wait a minute. Each client address may send /mcp 600 requests a minute (429 past that).
• Secrets stay out of the assistant. Creating an API key, a signing key or a webhook secret through the MCP is refused, because the secret is shown only once and would pass through the assistant's model. Create those from your backend or the Calloop dashboard. Any secret-looking field in a response is masked as [redacted]. Never paste a key or secret into the conversation: the connection's header is the only place your API key goes.
• Tools are marked read-only or destructive. api_change is marked destructive and agent_test_token as not read-only (it hands out a credential), so your client asks you before each call unless you've allowed it. Read what it is about to send: a PUT replaces the whole entity (Conventions).
• Use a key just for the assistant. Create it from your backend or the dashboard with an expiry (POST /v1/api-keys { "name": "ai-assistant", "expires_in_days": 30 }), and revoke it when you're done (DELETE /v1/api-keys/{id}, Keys). Prefer a test tenant while you build.
• Test tokens are for testing. They last at most 60 minutes, and each one issued is recorded. A SUPERVISOR token can listen to the tenant's live calls, so ask for AGENT unless you're testing supervisor features. In production your backend signs agent tokens itself with your signing key (agent protocol). Your app never holds the API key.
• What comes back is your account's data, as /v1 returns it: a call list holds your customers' numbers and names, and your assistant's provider sees whatever the tools return. That data is never instructions. The server tells the assistant not to act on text found in it, and your client's confirmation before each change is the backstop.
• Answers from /mcp are never cached (Cache-Control: no-store).

Errors

A tool that fails says what happened and what to do, for example "This tool needs your Calloop API key…" or "No docs page "api/queuez". Did you mean: api/queues?". An API error comes back as the API sent it, { status, body: { error: { code, message, details } } } (Errors), so the assistant can fix the request.