Build with Claude Code, Codex or Cursor

Install ThunderPhone Agent Skills, connect the ThunderPhone MCP server, and give a coding agent current product documentation.

ThunderPhone provides three layers for coding agents:

Skills explain how to do the work. MCP lets the coding agent inspect and act on your organization. Raw docs provide the source material for questions outside a loaded skill.

Install in a project#

This block installs the skills, makes the key available to the current shell, and adds the project-scoped MCP server to Claude Code. Replace the placeholder by reading the real value from your secret manager; do not paste a key into a repository or chat.

npx skills add thunderphone/skills
export THUNDERPHONE_API_KEY='replace-with-value-from-your-secret-manager'
claude mcp add --transport http --scope project \
  --header 'Authorization: Bearer ${THUNDERPHONE_API_KEY}' \
  thunderphone https://api.thunderphone.com/v1/mcp

For Codex, replace the final command with:

codex mcp add thunderphone \
  --url https://api.thunderphone.com/v1/mcp \
  --bearer-token-env-var THUNDERPHONE_API_KEY

Cursor reads a project configuration from .cursor/mcp.json:

{
  "mcpServers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}

VS Code uses the same server under a servers key in .vscode/mcp.json:

{
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}

Example session: bilingual dental receptionist#

1. Ask the coding agent to load create-agent, thunderphone-prompt-builder, build-tool-integration, add-knowledge, and test-agent. Tell it to plan first and not create resources yet.
2. Give it verified practice facts, supported tasks, escalation rules and the two required locales. Have it check the live voice catalog and supported languages instead of inventing a voice or locale.
3. Ask for one production prompt built from general principles and facts. The agent should switch to the caller's supported language, keep speech concise, ask one question at a time, and avoid caller-response scripts.
4. Have it define a narrow scheduling tool and attach only the knowledge the receptionist needs. Test tool success, no availability, invalid input, timeout and human handoff before deployment.
5. Generate scenarios for both languages, interruptions, corrections, missing information, knowledge questions, scheduling failures and escalation. Run them, inspect transcripts and tool evidence, fix the smallest general rule, and rerun the same set.
6. Review the exact draft and test evidence, then explicitly authorize deploy and number attachment. Place a controlled audio call in each language before moving real traffic.

Improve an agent in a closed loop#

Once an agent takes calls, ask the coding agent to load iterate-on-agent. The skill runs the same loop ThunderPhone uses on its own agents, so each change is measured before it ships:

1. Read the agent, its prompt revisions and the prompt style guide. Prompt revisions are available over REST and MCP, so a coding agent can inspect recent prompt changes directly.
2. Build test sets. import_conversations turns recent calls into test conversations and their hardest moments into examples with answer keys; generate_conversations writes them for a new agent, including difficult callers aimed at the prompt's weak spots (those always go to the dev split). Each conversation sits in a dev split, for tuning, or a test split, for measuring once. A call whose caller is in a test split is held out: to an API key or OAuth token, over REST and MCP alike, it comes back as its id, start time and held_out: true only, writes on it are refused (held_out_call), and so are test scenarios promoted from it; leave it out when tuning.
3. Take a baseline with run_replays on the dev split. With Bolt v2, a turn with recorded audio is replayed as a live call would run it.
4. Edit the draft. review_prompt checks the prompt against the style guide and offers find and replace edits; update_agent applies them to the draft with prompt_edits; a second review with previous_prompt checks what changed. refactor_prompt rewrites a prompt that has collected too many patches, and reports any behavior it changed. When an edit adds or removes a behavior, refresh_conversations brings the test conversations up to the new prompt, restoring earlier versions where a rule came back.
5. Verify with run_replays against the baseline, reading the failures the way a caller would hear them. compare_configs tries a different audio tier, voice, endpointing or intelligence tier on the same dev examples; comparisons are dev-only.
6. Measure once on the test split. A test run replays one whole test cohort and its first result spends it, so each later test run, for any prompt, needs fresh test data from imported calls or generated conversations. Each example's engine is set before the run from its data (recorded audio replays exactly, text-only examples as text), totals come per engine, and nothing falls back to text: a cohort with recorded audio under a configuration other than Bolt v2 is refused (test_needs_exact_replay) and stays unused, so measure that configuration on dev. Coding agents get its totals only, so they cannot tune on it.
7. Listen to a run_simulation recording, or open a talk link and talk to the draft yourself.
8. Deploy when you say so.

Everything that spends credits quotes first: send dry_run: true for an estimate, then run with its quote_id and max_cost_cents, a hard cap. A quote pays for one run: conversation jobs, replay runs, and prompt reviews and refactors that call the model all use it up, durably, when they start, and a start that is refused or fails first leaves it usable; after it is used, repeat a failed run with a new dry run. Each request sets aside its most possible cost before it is sent, and the run is charged what it really cost, so leave the estimate's headroom. An exact replay sets aside about 85 cents to $1.25 per replay in flight for a typical turn (a normal turn plus one production re-run), against a real cost of a few cents: give replay runs a cap with room. A turn that still runs out of budget is counted apart and spends no test cohort. An agent runs one conversation job or replay run at a time. With OAuth, the prompt tools need the agents:write scope. When a call's recording is turned off or the call is deleted, the test conversations and examples taken from it are removed too. The test conversation, replay, prompt review and talk link tools are part of the agent iteration toolkit, which is enabled per organization while it is in beta; ask support to turn it on.

Use the Python or TypeScript SDK for typed REST requests.

Use REST instead of MCP when a build needs deterministic payloads, versioned fixtures, bulk orchestration, or an operation not present in the current MCP tool list. The API starts at https://api.thunderphone.com/v1; see the API introduction and MCP guide.