thunderphone-mcp-setup
Skill0 starsChanged 57 days agoMITView on GitHub
Configure or troubleshoot the ThunderPhone MCP server in Claude Code, Codex, Cursor, VS Code, Claude Desktop, or Gemini CLI. Use when someone asks to add https://api.thunderphone.com/v1/mcp, sign in with OAuth, choose MCP versus REST, inspect MCP coverage, or verify a coding-agent connection.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-knowledgeSkill
- build-tool-integrationSkill
- create-agentSkill
- embed-web-widgetSkill
- get-phone-numberSkill
- handle-inbound-callsSkill
- iterate-on-agentSkill
- migrate-from-blandSkill
- migrate-from-elevenlabsSkill
- migrate-from-retellSkill
- migrate-from-vapiSkill
- place-outbound-callsSkill
- run-campaignSkill
- setup-api-keySkill
- setup-webhooksSkill
- test-agentSkill
- thunderphone-prompt-builderSkill
- use-with-livekitSkill
- use-with-openai-realtimeSkill
- use-with-pipecatSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 19
Detect the client: Check the current tool's documented project config:
- Distinctive: line 31
Do not write several configs unless the project intentionally supports several clients.
- Distinctive: line 59
Never write the key into a project file, a command line, or chat.
- Distinctive: line 60
Choose MCP or REST per task: Prefer MCP for interactive discovery and agent-assisted workflows across resources.
- Very specific: line 74
After installing @thunderphone/mcp globally, the equivalent command is thunderphone-mcp setup.
- Distinctive: line 94
Follow the ThunderPhone MCP guide and API introduction.
- Distinctive: line 95
Never ask for, print, commit, or pass a ThunderPhone API key.
- Distinctive: line 96
Read before mutating and ask for authority before external calls, campaigns, deletion, or other material side effects.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Configure the ThunderPhone MCP server
The server is https://api.thunderphone.com/v1/mcp (Streamable HTTP). Clients
sign in with OAuth (https://thunderphone.com/docs/guides/oauth): the first tool
call opens a browser, the user approves one ThunderPhone organization and the
scopes, and the client stores the token itself. No configuration file holds a
credential, and nothing reads one from the user's machine.
- Detect the client. Check the current tool's documented project config:
| Client | Project configuration |
| Claude Code | .mcp.json with mcpServers, or claude mcp add |
| Codex | plugin mcp.json, or codex mcp add then codex mcp login thunderphone |
| Cursor | .cursor/mcp.json with mcpServers |
| VS Code | .vscode/mcp.json with servers |
| Claude (web, desktop, mobile) | add ThunderPhone from the connector directory, or a custom connector with the URL above |
| Gemini CLI | .gemini/settings.json with mcpServers and an HTTP URL |
| Windsurf | user ~/.codeium/windsurf/mcp_config.json with mcpServers and serverUrl |
Do not write several configs unless the project intentionally supports several clients. Preserve unrelated servers in an existing file. 2. Add the endpoint with no headers. Copy the checked-in root, Cursor, VS Code, or Codex config matching the client. For Claude Code:
claude mcp add --transport http --scope project thunderphone https://api.thunderphone.com/v1/mcpFor Codex:
codex mcp add thunderphone --url https://api.thunderphone.com/v1/mcp
codex mcp login thunderphone- Sign in. Reload the client and run any ThunderPhone tool, or the
client's MCP sign-in command (
/mcpin Claude Code). Approve the organization in the browser window that opens. - Inspect the tool list. ThunderPhone MCP covers agents, numbers, calls,
testing, knowledge, tools/webhooks, voices, agent imports, and documentation;
tools/listis the live catalog for this connection. Callget_connection_identityto confirm which organization the token reaches. - Clients without OAuth. A client that cannot sign in with OAuth can send an organization API key as a bearer header instead. The user creates the key in the dashboard (Settings → API keys) and enters it in that client's own secret or credential field; follow the ThunderPhone MCP guide. Never write the key into a project file, a command line, or chat.
- Choose MCP or REST per task. Prefer MCP for interactive discovery and agent-assisted workflows across resources. Prefer REST for deterministic CI, explicit payload/version control, bulk orchestration, or an operation not yet exposed as an MCP tool. The same safety and authorization rules apply.
CLI setup and stdio alternative
These options complement the direct HTTP configurations above. Node 18.18+ is required.
npx -y @thunderphone/mcp setup --client cursor
npx -y @thunderphone/mcp setup --client claude-desktop --scope userAfter installing @thunderphone/mcp globally, the equivalent command is
thunderphone-mcp setup. Supported clients are claude-code, codex, cursor,
vscode, gemini, claude-desktop, and windsurf. Setup preserves unrelated
servers and prints the file written. It detects a single project client when
--client is omitted; non-interactive ambiguous detection requires that flag.
Desktop and Windsurf require --scope user. Desktop uses the stdio wrapper,
which signs in with thunderphone login; other clients use direct HTTP with
client-managed OAuth.
Errors
| Symptom | Cause | Fix |
| Server is absent after editing | Wrong config scope/name or client was not reloaded | Use the client-specific path, preserve its expected top-level key, and reload. |
401 or a sign-in prompt on every call | The OAuth sign-in was not finished, or the organization access was revoked | Run the client's MCP sign-in again and approve the organization. |
| Tools from the wrong organization | The token was approved for another organization | Sign out of the server in the client, sign in again, and pick the right organization. |
| Expected tool is missing | Role, server rollout, or cached discovery differs | Refresh tools, confirm role and current MCP docs, then use REST if necessary. |
Source and safety rules
- Follow the ThunderPhone MCP guide and API introduction.
- Never ask for, print, commit, or pass a ThunderPhone API key; OAuth needs none.
- Read before mutating and ask for authority before external calls, campaigns, deletion, or other material side effects.
- MCP discovery is current evidence; do not invent a tool because a REST endpoint exists.
See references/client-configs.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.