--- title: MCP-Server description: KI-Assistenten (Claude, Cursor, VS Code u. a.) über den integrierten MCP-Endpunkt unter /mcp mit der API verbinden: Auth, Konfiguration und Tools. url: https://nexcmp.com/de/docs/developers/mcp/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # MCP-Server {#mcp-server} > **Where in the portal:** API reference › Tools (`https:///apidoc`) zeigt den Endpunkt und Client-Snippets; Schlüssel werden unter API keys (`/api-keys`) erstellt. Es gibt keine Admin-Einstellung: Der Endpunkt ist Teil des Panels. ## Funktion {#what-it-does} Das **Model Context Protocol (MCP)** ermöglicht es einem KI-Assistenten, Tools aufzurufen. NexCMP stellt einen MCP-Endpunkt unter `https:///mcp` bereit. Jede öffentliche API-Operation wird zu einem **Tool** (`vm_list`, `vm_start`, `billing_wallet`, ...), sodass ein Kunde seinen Assistenten fragen kann: „Welche meiner VMs laufen?“ oder „Stoppe die Staging-VM“. Der Assistent agiert ausschließlich mit dem eigenen API-Schlüssel und den Berechtigungen des Kunden. ::: tip NexCMP selbst mit KI konfigurieren? Diese Seite beschreibt den **Kunden**-MCP-Endpunkt (`/mcp`). Informationen darüber, wie Sie einen KI-Assistenten als Administrator Ihr eigenes Panel konfigurieren lassen, finden Sie unter [Configure with AI](https://nexcmp.com/de/docs/configure-with-ai/mcp-admin/) (Endpunkt `/mcp/admin`, Admin-Schlüssel `ak_`). ::: ## Anforderungen {#requirements} | Komponente | Anforderung | |---|---| | Server | Nichts zu installieren: Der Endpunkt wird vom Panel bereitgestellt und ist überall dort erreichbar, wo das Panel erreichbar ist. Ihr Reverse Proxy muss `/mcp` an das Panel weiterleiten. | | Kunde | Ein [API key](https://nexcmp.com/de/docs/developers/api-keys/) (`vk_...`) mit den vom Assistenten benötigten Scopes. | | Client | Ein MCP-Client, der den **Streamable HTTP**-Transport und einen benutzerdefinierten `Authorization`-Header unterstützt: Claude Code, Claude Desktop (über die `mcp-remote`-Bridge), Cursor, VS Code mit Copilot-Agentenmodus und ähnliche. | | Protokollversionen | 2025-11-25, 2025-06-18 und 2025-03-26. | ## Infrastruktur vorbereiten {#prepare-the-infrastructure} Nichts, außer sicherzustellen, dass `https:///mcp` nicht durch eine Firewall oder eine Proxy-Regel blockiert wird. Ein browserbasierter MCP-Client von einem anderen Ursprung wird abgelehnt, es sei denn, dieser Ursprung ist zugelassen; Befehlszeilen- und Desktop-Clients senden keinen `Origin`-Header und funktionieren wie gewohnt. ## Verbinden (Kundenseite) {#connect-customer-side} 1. Erstellen Sie im Portal einen API-Schlüssel (**API keys › Create key**) mit nur den Scopes, die der Assistent verwenden soll, einer kurzen Gültigkeitsdauer und nach Möglichkeit einer IP-Beschränkung. 2. Fügen Sie den Server zu Ihrem Client hinzu. Ersetzen Sie `cloud.example.com` und den Schlüssel. **Claude Code** ```bash claude mcp add --transport http cloud https://cloud.example.com/mcp \ --header "Authorization: Bearer vk_XXXX" ``` **Cursor** (`~/.cursor/mcp.json` oder `.cursor/mcp.json`; legen Sie `CLOUD_API_KEY` in der Umgebung fest, aus der Cursor gestartet wird): ```json { "mcpServers": { "cloud": { "url": "https://cloud.example.com/mcp", "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" } } } } ``` **Claude Desktop** (benötigt Node.js 18+; `claude_desktop_config.json`), über die `mcp-remote`-Bridge: ```json { "mcpServers": { "cloud": { "command": "npx", "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"], "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" } } } } ``` Schreiben Sie den Header ohne Leerzeichen nach dem Doppelpunkt und fügen Sie den gesamten Wert wie oben in die Umgebungsvariable ein. 3. Starten Sie den Client neu und fordern Sie ihn auf, Ihre Tools aufzulisten. Überprüfen Sie die Verbindung ohne Client: ```bash curl -s https://cloud.example.com/mcp \ -H "Authorization: Bearer vk_XXXX" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Wie es funktioniert {#how-it-works} | Komponente | Detail | |---|---| | Endpoint | `POST /mcp` mit einer JSON-RPC 2.0-Nachricht; die Antwort ist `application/json`. `GET /mcp` antwortet mit 405 (kein Server-zu-Client-Stream); `DELETE /mcp` beendet die Sitzung. | | Authentifizierung | Nur `Authorization: Bearer vk_...` (Sitzungstokens, Cookies und Adminschlüssel werden mit 401 und einem `WWW-Authenticate: Bearer`-Header abgelehnt). | | Sitzung | `Mcp-Session-Id` wird von `initialize` ausgestellt, an diesen Schlüssel gebunden und ist 24 Stunden gültig; maximal 16 Sitzungen pro Schlüssel. | | Tools | Eine pro öffentlicher API-Operation, die für den Schlüssel sichtbar ist. Der Tool-Name entspricht dem CLI-Befehl, bei dem Leerzeichen und Bindestriche durch `_` ersetzt wurden (aus `vm firewall add` wird `vm_firewall_add`), und stimmt mit dem OpenAPI-`operationId` überein. Ein Tool wird nur aufgelistet, wenn der Schlüssel über den entsprechenden Scope verfügt und das Modul aktiviert ist. | | Funktionen | Nur Tools (keine Ressourcen oder Prompts). | | Größe | Anfragetext bis zu 1 MB; Tool-Ergebnistext bis zu ca. 100 KB (der Rest wird mit einem Hinweis abgeschnitten); ein Aufruf dauert höchstens 55 Sekunden. | ### Sicherheitsregeln {#safety-rules} - **Gleiches Tor wie die REST-API.** Jedes `tools/call` durchläuft die panel-eigene Anfragenpipeline: Scope, Site, IP-Beschränkung, Rate-Limit, Idempotenz, Inhaberschaftsprüfungen (404 für Ressourcen anderer Personen) und Quotas greifen uneingeschränkt. MCP kann nichts gewähren, worüber der Schlüssel nicht verfügt. - **Bestätigung.** Tools, die kostenpflichtig sind, Daten löschen oder Anmeldedaten zurückgeben (Konsolentickets, Kubeconfig, S3- oder SSH-Geheimnisse, Passwortresets, neue Schlüssel), erfordern das Argument `confirm: true`. Die Tool-Beschreibung weist den Assistenten an, dieses nur nach Bestätigung durch den Benutzer zu übergeben, sodass eine in einer Webseite oder einem Protokoll versteckte Anweisung dies nicht eigenständig auslösen kann. - **Idempotenz.** Kostenpflichtige Tools akzeptieren `idempotency_key`; wird dies weggelassen, wird aus dem Tool-Namen und den Argumenten ein stabiler Schlüssel abgeleitet, sodass ein identischer Wiederholungsversuch nicht doppelt berechnet werden kann. - **Nicht als Tools verfügbar:** Streaming-Endpunkte (der AI Agent-Chat), einmalige SSH- oder Konsolen-WebSocket-Tickets, Binärdownloads und die Endpunkte der VPN-App (`/v1/ext/*`). - **Niemals möglich:** Die API erlaubt zu keinem Zeitpunkt Aufladungen, Passwortänderungen, das Löschen des Kontos oder das Erstellen von Schlüsseln, sodass kein Assistent diese Aktionen ausführen kann. ### Limits {#limits} | Limit | Standard | |---|---| | Tool-Aufrufe pro Schlüssel | 60 pro Minute | | MCP-Anfragen pro Schlüssel | 240 pro Minute | | Plus die normalen Schlüssel- und Kontolimits | Siehe [REST API](https://nexcmp.com/de/docs/developers/api/#rate-limits) | Bei Überschreitung des Limits antwortet der Endpunkt mit HTTP 429, einem JSON-RPC-Fehler und `Retry-After`. ## Verifizierung {#verify} 1. Der obige Befehl `curl` gibt ein JSON-RPC-Ergebnis mit einer `tools`-Liste zurück. Es werden nur Tools angezeigt, die zu den Scopes des Schlüssels passen. 2. Fragen Sie in Ihrem Client „list my VMs“: Der Assistent ruft `vm_list` auf und zeigt das Ergebnis an. 3. Im Portal aktualisiert sich die Zeit unter **Last used** des Schlüssels, und Schreibaufrufe erscheinen im **Key usage log**. ## Limits & Hinweise {#limits-notes} - **Browser-Anmeldung (OAuth).** Die Referenzseite beschreibt auch die Anmeldung über den Browser für Clients, die MCP OAuth unterstützen. Bei einer installierten NexCMP ist die unterstützte und getestete Methode der API-Schlüssel (oder `cmp login` für die CLI). - **Reseller-Seiten** zeigen den MCP-Bereich nicht an; deren Kunden verwenden die Domain des Resellers für die API. - **Minimalprivileg.** Erstellen Sie pro Assistent einen dedizierten Schlüssel mit zunächst Lese-Scopes; fügen Sie Schreib-Scopes nur bei Bedarf hinzu. - Widerrufen Sie den Schlüssel unter **API keys**, um den Zugriff des Assistenten sofort zu trennen. ## Fehlerbehebung {#troubleshooting} | Symptom | Ursache | Behebung | |---|---|---| | 401 mit `WWW-Authenticate: Bearer` | Kein Schlüssel, falscher Schlüssel oder ein Sitzungstoken | Senden Sie `Authorization: Bearer vk_...`. | | 403 zu `Origin` | Eine Browserseite von einem anderen Ursprung | Verwenden Sie einen Desktop- oder CLI-Client oder bitten Sie Ihren Administrator, den Ursprung zu erlauben (`mcp_allowed_origins`). | | 404 bei einer Anfrage mit `Mcp-Session-Id` | Sitzung gehört zu einem anderen Schlüssel oder ist abgelaufen | Führen Sie `initialize` erneut aus. | | 405 bei `GET /mcp` | Erwartet: Der Server verfügt über keinen Event-Stream | Verwenden Sie ausschließlich POST (Clients tun dies automatisch). | | Die Tool-Liste ist kurz | Schlüssel-Scopes oder Module | Fügen Sie dem Schlüssel Scopes hinzu; aktivieren Sie das Modul. | | Tool antwortet, dass es `confirm: true` benötigt | Kostenpflichtiges, löschendes oder sensibles Tool | Der Assistent muss `confirm` festlegen, nachdem Sie zugestimmt haben. | | 429 | MCP- oder Schlüssel-Rate-Limit | Warten Sie auf `Retry-After`. | | Client kann keine Verbindung mit einem Header herstellen | Client ohne Unterstützung für benutzerdefinierte Header | Verwenden Sie die `mcp-remote`-Brücke. |