MCP-Server

Where in the portal: API reference › Tools (https://<your-domain>/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

Das Model Context Protocol (MCP) ermöglicht es einem KI-Assistenten, Tools aufzurufen. NexCMP stellt einen MCP-Endpunkt unter https://<your-domain>/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.

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 (Endpunkt /mcp/admin, Admin-Schlüssel ak_).

Anforderungen

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 (`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

Nichts, außer sicherzustellen, dass https://<your-domain>/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)

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.

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.

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

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

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

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

Bei Überschreitung des Limits antwortet der Endpunkt mit HTTP 429, einem JSON-RPC-Fehler und Retry-After.

Verifizierung

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.
Fragen Sie in Ihrem Client „list my VMs“: Der Assistent ruft vm_list auf und zeigt das Ergebnis an.
Im Portal aktualisiert sich die Zeit unter Last used des Schlüssels, und Schreibaufrufe erscheinen im Key usage log.

Limits & Hinweise

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

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.

MCP-Server ​

Funktion ​

Anforderungen ​

Infrastruktur vorbereiten ​

Verbinden (Kundenseite) ​

Wie es funktioniert ​

Sicherheitsregeln ​

Limits ​

Verifizierung ​

Limits & Hinweise ​

Fehlerbehebung ​