MCP server · TrunkBeam Docs

Early access: these interfaces are documented as drafts. Confirm commands, packages and endpoints with us before use.

MCP server

Manage numbers straight from Claude Code, Codex, Cursor or any other MCP client.

Through the MCP server your coding agent can search, buy and connect numbers and set transfer targets. You say in one sentence what you need, and the agent calls the right tools.

The server comes in two variants:

Local via npx @trunkbeam/mcp. Runs on your machine, the API key lives in an environment variable.
Hosted at https://mcp.trunkbeam.example/mcp. Nothing to install, authentication with your API key in a header.

Tools

Tool	What it does	Confirmation
`search_numbers`	Search available numbers in an area code	no
`get_price`	Show the price of a number and its minutes	no
`buy_number`	Buy a number and connect it to a SIP target	yes
`list_numbers`	Your numbers with status	no
`update_routing`	Change the SIP target of a number	no
`set_transfer_targets`	Set allowed targets for SIP REFER	no
`release_number`	Cancel a number at month end	yes
`get_verification_status`	Verification status of your account	no
`get_usage`	Usage and cost for the current month	no

Tools that need confirmation cost money or cannot be undone. The agent shows you the number and price first, and nothing happens until you confirm.

Claude Code

claude mcp add trunkbeam \
  -e TRUNKBEAM_API_KEY=tb_live_… \
  -- npx -y @trunkbeam/mcp

With --scope user the server is available in all projects. With --scope project it goes into the repo’s .mcp.json and to your whole team. Check with:

claude mcp list

Codex

codex mcp add trunkbeam \
  --env TRUNKBEAM_API_KEY=tb_live_… \
  -- npx -y @trunkbeam/mcp

Or directly in ~/.codex/config.toml:

[mcp_servers.trunkbeam]
command = "npx"
args = ["-y", "@trunkbeam/mcp"]

[mcp_servers.trunkbeam.env]
TRUNKBEAM_API_KEY = "tb_live_…"

Check with codex mcp list.

Cursor

In .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "trunkbeam": {
      "command": "npx",
      "args": ["-y", "@trunkbeam/mcp"],
      "env": { "TRUNKBEAM_API_KEY": "tb_live_…" }
    }
  }
}

Other clients

Claude Desktop, Windsurf and most other clients read the same mcpServers block as Cursor. For Claude Desktop it goes into claude_desktop_config.json.

Hosted server

Claude Code:

claude mcp add --transport http trunkbeam https://mcp.trunkbeam.example/mcp \
  -H "Authorization: Bearer $TRUNKBEAM_API_KEY"

Codex reads the key from an environment variable:

codex mcp add trunkbeam \
  --url https://mcp.trunkbeam.example/mcp \
  --bearer-token-env-var TRUNKBEAM_API_KEY

In ~/.codex/config.toml:

[mcp_servers.trunkbeam]
url = "https://mcp.trunkbeam.example/mcp"
bearer_token_env_var = "TRUNKBEAM_API_KEY"

Keys for agents

Give your agent its own key with a spend limit. Once it hits the limit, the server rejects further purchases until you raise it.

trunkbeam keys create --name coding-agent --scope numbers:read,numbers:write --spend-limit 20

Example

Get us a Hamburg number and route it to sip:agent@voice.example.

The agent calls search_numbers with area code 040, shows you the number and price, waits for your OK and then calls buy_number.