# MCP-Server

Nummern direkt aus Claude Code, Codex, Cursor oder jedem anderen MCP-Client verwalten.

> Early Access: Die Schnittstellen sind als Entwurf dokumentiert. Befehle, Pakete und Endpunkte vor der Nutzung mit uns abstimmen.

Quelle: https://trunkbeam.com/docs/mcp

Über den MCP-Server kann dein Coding-Agent Nummern suchen, kaufen, verbinden und Weiterleitungsziele setzen. Du sagst in einem Satz, was du brauchst, der Agent ruft die passenden Werkzeuge auf.

Den Server gibt es in zwei Varianten:

- **Lokal** über `npx @trunkbeam/mcp`. Läuft auf deinem Rechner, der API-Schlüssel steht in einer Umgebungsvariable.
- **Gehostet** unter `https://mcp.trunkbeam.example/mcp`. Nichts zu installieren, Anmeldung per API-Schlüssel im Header.

## Werkzeuge

| Werkzeug | Was es macht | Rückfrage |
| --- | --- | --- |
| `search_numbers` | Freie Nummern in einem Ortsnetz suchen | nein |
| `get_price` | Preis einer Nummer und der Minuten anzeigen | nein |
| `buy_number` | Nummer kaufen und mit einem SIP-Ziel verbinden | ja |
| `list_numbers` | Deine Nummern mit Status | nein |
| `update_routing` | SIP-Ziel einer Nummer ändern | nein |
| `set_transfer_targets` | Erlaubte Ziele für SIP REFER setzen | nein |
| `release_number` | Nummer zum Monatsende kündigen | ja |
| `get_verification_status` | Prüfstatus deines Kontos | nein |
| `get_usage` | Verbrauch und Kosten im laufenden Monat | nein |

Werkzeuge mit Rückfrage kosten Geld oder lassen sich nicht rückgängig machen. Der Agent zeigt dir vorher Nummer und Preis, erst nach deiner Bestätigung passiert etwas.

## Claude Code

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

Mit `--scope user` steht der Server in allen Projekten zur Verfügung, mit `--scope project` landet er in der `.mcp.json` des Repos und damit bei deinem ganzen Team. Prüfen mit:

```bash
claude mcp list
```

## Codex

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

Oder direkt in `~/.codex/config.toml`:

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

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

Prüfen mit `codex mcp list`.

## Cursor

In `.cursor/mcp.json` im Projekt oder in `~/.cursor/mcp.json` für alle Projekte:

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

## Andere Clients

Claude Desktop, Windsurf und die meisten anderen Clients lesen denselben `mcpServers`-Block wie Cursor. Bei Claude Desktop steht er in `claude_desktop_config.json`.

## Gehosteter Server

Claude Code:

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

Codex liest den Schlüssel aus einer Umgebungsvariable:

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

In `~/.codex/config.toml` sieht das so aus:

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

## Schlüssel für Agenten

Gib deinem Agenten einen eigenen Schlüssel mit Ausgabelimit. Erreicht er das Limit, lehnt der Server weitere Käufe ab, bis du es anhebst.

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

## Beispiel

> Hol uns eine Hamburger Nummer und leite sie auf sip:agent@voice.example.

Der Agent ruft `search_numbers` mit Vorwahl 040 auf, zeigt dir Nummer und Preis, wartet auf dein OK und ruft dann `buy_number` auf.