MCP server: let your coding agent test your voice agent

CallQA runs a Model Context Protocol server. Connect your coding agent (Claude Code, Cursor, Codex, VS Code, or any MCP client) and ask it, in plain words:

Test my voice agent on staging with CallQA, tell me what breaks and fix my prompt.

The agent lists your scenarios, starts a run on the right environment, waits for the verdicts, reads the failed calls (transcript, the judge's quotes) and fixes your code. When a test itself is wrong, it can ask the CallQA assistant for a corrected scenario and show you the diff before saving it.

It can also set CallQA up from zero, without the dashboard:

Set up CallQA for the voice agent in this repository: staging and production, tests every weekday morning, and the CI.

See Onboarding with an agent.

Connect

The quickest way: in the app, open Developer > MCP server. An admin creates a key with the recommended scopes (read, write, run) and the page shows the install command of each client with the key in it, and the prompt to paste in your agent. The same block, with a placeholder for the key, is at the top of the Quickstart.

Any API key works (see Authentication). The examples below read it from the CALLQA_API_KEY environment variable, so no key lands in a file: set it first with export CALLQA_API_KEY="cqa_..." (your own key).

Claude Code

claude mcp add --transport http callqa https://app.callqa.dev/mcp \
  --header "Authorization: Bearer $CALLQA_API_KEY"

Add --scope user to use it in every project. Check with claude mcp list.

Cursor

In ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "callqa": {
      "url": "https://app.callqa.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:CALLQA_API_KEY}" }
    }
  }
}

VS Code

In .vscode/mcp.json (VS Code asks for the key once and stores it securely):

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

Codex

In ~/.codex/config.toml (Codex reads the key from CALLQA_API_KEY):

[mcp_servers.callqa]
url = "https://app.callqa.dev/mcp"
bearer_token_env_var = "CALLQA_API_KEY"

Other clients

Any client that speaks Streamable HTTP and lets you set a header works. Clients that only start local (stdio) servers can go through the mcp-remote bridge:

npx mcp-remote https://app.callqa.dev/mcp --header "Authorization: Bearer $CALLQA_API_KEY"

From a script, with the Python SDK (pip install "mcp>=2.2"):

import asyncio, os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client


async def main():
    headers = {"Authorization": f"Bearer {os.environ['CALLQA_API_KEY']}"}
    async with httpx2.AsyncClient(headers=headers, timeout=330) as http:
        async with Client(streamable_http_client("https://app.callqa.dev/mcp", http_client=http)) as c:
            print([t.name for t in (await c.list_tools()).tools])
            print((await c.call_tool("list_scenarios", {})).structured_content)


asyncio.run(main())

To try the tools by hand: npx @modelcontextprotocol/inspector, transport "Streamable HTTP", the URL above and the Authorization header.

Tools

Every tool has typed inputs and outputs (inputSchema, outputSchema) and a description written for the model. Each needs the scope shown, like the matching REST endpoint.

Setup tools:

Support tools (see Getting help):

run_scenario places real phone calls: each one consumes your monthly quota, then wallet credit, under your wallet, spend cap and plan limits, exactly like a run started from the API. wait_s (up to 300 seconds) keeps the request open until the run finishes and streams progress notifications; without it the tool returns at once and the agent polls get_run_report. set_schedule and the CI files lead to more of these calls, on their own: their answers say how many. place_verification_call places one real call that costs nothing. Nothing can be deleted or paid through the MCP server.

Resources and prompts

Prompts (shown as slash commands by most clients): test-my-voice-agent (arguments environment, scenario), investigate-failing-run (run_id), write-scenario (description, phone) and set-up-callqa (description, phone, environments, schedule).

Onboarding with an agent

The prompt set-up-callqa walks the agent through the setup in this order. Every step is a tool call; the agent stops where a person has to act.

1. Status. get_setup_status: plan, credit, the key's scopes, what is done.
2. Environments. create_environment for each deployment of the voice agent (development, staging, production). Every organization starts with one, the default.
3. Number and verification. add_phone_number, then:
4. A person signs the attestation: the agent shows the text (get_number_status) and signs with start_number_verification(sign_attestation=true, signer_name=...) only in the name and with the agreement of the person who controls the line. It is a legal statement; the agent never signs on its own.
5. The line says the code: the agent adds the returned phrase to the voice agent's prompt or greeting when that prompt lives in your repository, and asks you to deploy. Otherwise you add it in your voice platform.
6. place_verification_call, then get_number_status until verified. Until then only manual calls work (sandbox: 3 a day, no schedule, no CI). See Number verification.
7. Scenarios from a plain description of the agent, or from its prompt and flows in your repository: validate_scenario_yaml, create_scenario.
8. A first run: run_scenario on one scenario, get_run_report. Real calls: the agent says how many before starting.
9. Schedules: set_schedule per scenario and environment, for example schedule="every weekday at 08:30", timezone="Europe/Paris", call_window="08:00-20:00". The answer has the month's forecast.
10. Webhooks and alerts: configure_webhook, create_alert_channel. They need a key with the admin scope; with the recommended key, an admin sets them up in the app instead.
11. CI: get_ci_setup returns the files to commit (.github/workflows/callqa.yml and the CallQA action, or .gitlab-ci.callqa.yml), the CLI to download and the secret to set. A person stores a key with the read and run scopes as the CALLQA_API_KEY secret (gh secret set CALLQA_API_KEY): no key is ever written in a file.

What only a person does: sign the attestation of a number, make the line say the verification code when its prompt is not in the repository, choose a plan or top up the wallet (never through an API key), create API keys, and, with a key without the admin scope, webhooks and alerts.

Security

• Same rules as the REST API. The key's scopes, its IP allow list, its expiry and the rate limit (120 requests per minute per key) apply to every MCP request. Objects of other organizations answer not_found.
• Journal. Each request is a line of the API journal (Developer > API journal), for example POST /mcp tools/call run_scenario. Tool arguments are not logged. Changes are in the audit log under the key.
• Least privilege. Give the agent read, write and run, never admin. A read only key is enough for an agent that only reads reports.
• Browsers. Requests carrying a browser Origin from another site are refused.

Errors

A tool that fails answers an error result whose text is JSON, with the stable codes of the REST API (see Errors) and a hint for the model:

{"error": {"code": "missing_scope", "status": 403,
           "detail": "This API key lacks the 'run' scope (run.trigger).",
           "hint": "Ask an admin of the organization for a key with this scope (...)."}}

Codes you will meet: missing_scope, feature_not_in_plan (with required_plan and upgrade_url), not_found, invalid_scenario (with errors, one per field), run_not_possible, blocked_insufficient_credit (no call of the run could be paid, with run_id and block_reasons), blocked_policy (no call of the run could be placed for a policy reason, same fields), call_not_judged, call_passed (fix_test on a call that passed), not_pending, scenario_changed, rate_limited; for the setup tools, already_exists, invalid_target, attestation_required, no_active_code, invalid_schedule, unknown_event, unsafe_url, no_scenario. Before the protocol starts, the HTTP layer answers 401 unauthorized, 403 ip_not_allowed or 429 rate_limited (with Retry-After).