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.dev; ü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.