Claude Desktop einrichten

1. API-Key holen

Geh in deinem Dashboard zu Org Settings → API Keys → Create. Vergib den Scope mcp:* (deckt alle fünf Tools unten ab). Das Secret wird nur einmal angezeigt; kopiere den vollständigen snt_live_<prefix>.<secret>-String.

Speichere ihn im OS-Keychain oder in einer lokalen .env — niemals committen. Der Key ist an deine Org gebunden (und optional an ein Projekt); Calls außerhalb des Scopes liefern 404. Aus dem Dashboard jederzeit widerrufbar; widerrufene Keys liefern beim nächsten Call 401.

2. Installieren (oder überspringen)

Der MCP-Server ist auf npm und Homebrew veröffentlicht. Mit npx musst du nichts installieren — Claude Desktop zieht bei jedem Start die neueste Version. Mit brew bekommst du ein gepinntes lokales Binary, nützlich hinter strikten Firewalls.

1// keine Installation nötig — npx zieht das neueste @sonenta/mcp on demand2npx -y @sonenta/mcp --version

1// optional: einmal global installieren — kommt mit dem V1-Launch2brew install sonenta/tap/sonenta-mcp

3. Claude Desktop verdrahten

Öffne die Config-Datei von Claude Desktop, füge den sonenta-Eintrag unter mcpServers hinzu, beende die App und starte sie neu.

1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "sonenta": {6      "command": "npx",7      "args": ["-y", "@sonenta/mcp"],8      "env": {9        "SONENTA_API_KEY": "snt_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

Drei Env-Variablen insgesamt: SONENTA_TOKEN (erforderlich), SONENTA_PROJECT (optional — pre-scope ein Projekt, damit der Agent nicht zuerst list_projects aufrufen muss) und SONENTA_API_BASE (optional — Default https://api.sonenta.com; überschreibe für Self-Hosted oder Staging).

SONENTA_PROJECTS erfordert @sonenta/mcp ≥ 0.11.0. Bei älteren Releases siehe Rückwärtskompatibilität weiter unten.

Tool-Aufrufe über mehrere Projekte

Wenn SONENTA_PROJECTS mehr als eine UUID auflistet, kann der Agent nicht erraten, von welchem Projekt Sie sprechen — jeder Tool-Aufruf muss project_uuid enthalten. Mit einer einzelnen UUID (oder nur dem alten SONENTA_PROJECT) ist es optional und der Aufruf greift standardmäßig auf dieses Projekt zurück.

1// list_missing_keys — project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID2{3  "name": "list_missing_keys",4  "arguments": {5    "project_uuid": "<uuid1>",6    "namespace": "checkout",7    "language_code": "ja"8  }9}

Formulieren Sie Ihren Prompt mit dem Projekt im Sinn (« im Checkout-Projekt, liste die fehlenden Schlüssel für ja auf ») — der Agent löst das Projekt zu seiner UUID auf und übergibt project_uuid beim Tool-Aufruf. Bei einem über mehrere Projekte mehrdeutigen Prompt ruft der Agent zuerst list_projects auf.

Cursor (und andere MCP-Clients)

Gleiches JSON, andere Datei. In Cursor leg sie unter .cursor/mcp.json ab (projektweit) oder ~/.cursor/mcp.json (userweit). Für andere Clients folge der MCP-Config-Doku deines Clients — der mcpServers.sonenta-Eintrag bleibt gleich.

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "sonenta": {5      "command": "npx",6      "args": ["-y", "@sonenta/mcp"],7      "env": { "SONENTA_API_KEY": "snt_live_<prefix>.<secret>" }8    }9  }10}

Die 5 V1-Tools

Nach der Konfiguration stehen dem Agent diese Tools zur Verfügung. Du rufst sie nicht namentlich auf — beschreib deine Absicht im Chat, der Agent wählt aus. Die Namen unten sind die kanonischen Identifier, nützlich beim Lesen von Agent-Traces oder beim Bauen eigener Agents auf demselben Server.

Limits & Kontingente pro Plan

Sie zahlen, wenn ein Agent Ihr Projekt verändert, nicht wenn er es beobachtet. Lesezugriffe und Auflistungen sind kostenlos; Schreibvorgänge kosten eine Einheit; Bulk- und KI-unterstützte Vorgänge skalieren mit der geleisteten Arbeit.

Was als abrechenbarer Aufruf zählt

Obergrenzen pro Plan

Monatliches Kontingent, hartes Limit pro Minute, gleichzeitige MCP-Sitzungen und ob Schreibvorgänge erlaubt sind. Dieselben Werte speisen den Header X-MCP-Quota-Remaining bei jeder Antwort.

Wenn Sie eine Obergrenze erreichen

Über der Rate pro Minute → 429 mcp_rate_limited mit Retry-After (Sekunden). Über dem monatlichen Kontingent → 429 mcp_quota_exceeded mit Retry-After, ausgerichtet auf den Rollover. Schreibvorgänge im Free-Plan → 403 mcp_writes_disabled. Kontingente werden am 1. jedes Kalendermonats um Mitternacht UTC zurückgesetzt.

Funktion prüfen

1. 1 Starte Claude Desktop komplett neu (beenden, neu starten — die Config wird beim Start gelesen).
2. 2 Öffne einen neuen Chat. Das Hammer-Icon sollte sonenta mit 5 verfügbaren Tools zeigen.
3. 3 Tippe „List my Sonenta projects." Der Agent sollte list_projects aufrufen und deine Workspaces zurückgeben.

Hängst fest? Schau in die Logs von Claude Desktop unter ~/Library/Logs/Claude/mcp*.log (macOS). 90 % der Probleme sind Tippfehler im JSON oder ein veralteter Token.