Einen KI-Client verbinden (MCP)

Wo im Admin-Bereich: Unter System › Settings › API & AI agents (/agent/keys) zeigt der Tab Connect an AI die Endpunkt-URL sowie ein sofort kopierbares Snippet für jeden Client, gefüllt mit einem soeben erstellten Schlüssel.

Funktion

Das Model Context Protocol (MCP) ermöglicht es einem KI-Client, Tools aufzurufen. Ihr Panel stellt einen Admin-MCP-Server unter https://cloud.example.com/mcp/admin bereit. Verbinden Sie Ihr eigenes KI-Tool damit und fragen Sie in natürlicher Sprache: „Was muss noch eingerichtet werden?“, „Füge mein Proxmox-Cluster hinzu“, „Erstelle Tarife mit 40 % Marge“. Der Client ruft die unten stehenden Admin-Tools auf; das Panel prüft die Scopes, fragt Sie vor riskanten Aktionen und protokolliert jeden Aufruf.

Zwei MCP-Endpunkte

/mcp ist der Kundenendpunkt (Kunden-API-Schlüssel, vk_; siehe MCP server). /mcp/admin ist der hier beschriebene Admin-Endpunkt (Adminschlüssel ak_ oder OAuth). Die beiden vermischen sich nie: Admin-Tools sind auf /mcp nicht sichtbar und /mcp/admin akzeptiert ausschließlich Adminschlüssel.

Anforderungen

Komponente	Anforderung
Endpoint	https://cloud.example.com/mcp/admin auf der Domain Ihres Panels. Kopieren Sie die exakte URL vom Tab Connect an AI. Dieselbe Seite listet eine lokale URL (http://127.0.0.1:<port>/mcp/admin) für Tools auf, die direkt auf dem Server ausgeführt werden.
Anmeldeinformationen	Ein Admin-API-Schlüssel (ak_...) mit den gewünschten Scopes oder die OAuth-Anmeldung für Web-Connectors (OAuth connectors).
Client	Jeder MCP-Client, der den Streamable HTTP-Transport und einen benutzerdefinierten Authorization-Header unterstützt. Protokollversionen 2025-11-25, 2025-06-18 und 2025-03-26.
Netzwerk	Wenn Sie einen eigenen Reverse Proxy vor dem Panel betreiben, muss dieser /mcp/admin weiterleiten. Web-Connectors (claude.ai, ChatGPT) verbinden sich von den Servern des Anbieters aus, weshalb die URL aus dem Internet erreichbar sein muss.

Infrastruktur vorbereiten

Es muss nichts auf dem Server installiert werden. Wenn Sie den Schlüssel per IP einschränken, stellen Sie sicher, dass sich die Adresse Ihres Clients im entsprechenden Bereich befindet. Testen Sie die Erreichbarkeit zuerst:

curl -i -X POST https://cloud.example.com/mcp/admin

Eine Antwort von 401 mit einem WWW-Authenticate: Bearer ... resource_metadata=...-Header bedeutet, dass der Endpunkt erreichbar ist und Anmeldedaten erwartet.

In NexCMP verbinden

1. Einen Schlüssel erstellen: System › Settings › API & AI agents › API keys › New key. Verwenden Sie für den ersten Test nur admin:read; fügen Sie Schreib-Scopes hinzu, sobald Sie diese benötigen. Siehe Admin API keys.
2. Öffnen Sie den Tab Connect an AI. Solange der „Schlüssel erstellt“-Dialog noch geöffnet ist, enthält jedes Snippet unten bereits Ihren echten Schlüssel. Andernfalls wird der Platzhalter ak_YOUR_KEY angezeigt.
3. Kopieren Sie das Snippet für Ihren Client und führen Sie es aus oder fügen Sie es wie im Folgenden beschrieben ein.

Claude Code

claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"

Starten Sie dann claude und fragen Sie „list the tools from nexcmp“ oder „what is left to set up?“.

Am 30/10/2026 mit Claude Code 2.1 überprüft: claude mcp add --transport http … schreibt den Server (-s project hinzufügen, um ihn in .mcp.json zu behalten). Für Skripte läuft claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*" ohne Freigabe.

Claude Desktop

Erfordert Node.js 18 oder neuer. Fügen Sie dies zu claude_desktop_config.json hinzu (nutzt die mcp-remote-Brücke) und starten Sie Claude Desktop neu:

{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}

Wenn Ihr System das Leerzeichen im Header-Argument verfälscht, setzen Sie stattdessen den gesamten Wert in eine Umgebungsvariable, genau wie beim Kundenendpunkt: "args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"] mit "env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }.

claude.ai (eigener Connector)

Kein Schlüssel erforderlich: Die Anmeldung erfolgt über OAuth. Öffnen Sie in claude.ai die Connector-Einstellungen, fügen Sie einen eigenen Connector hinzu, fügen Sie https://cloud.example.com/mcp/admin ein, melden Sie sich mit Ihrem NexCMP-Admin-Konto an und wählen Sie die Berechtigungen auf dem Einwilligungsbildschirm aus. Details: OAuth connectors.

ChatGPT (Entwicklermodus)

Kein Schlüssel erforderlich. Aktivieren Sie in ChatGPT den Entwicklermodus, fügen Sie einen MCP-Connector mit der URL https://cloud.example.com/mcp/admin hinzu, wählen Sie OAuth und melden Sie sich mit Ihrem NexCMP-Admin-Konto an. Details: OAuth connectors.

Codex CLI

Hinzufügen zu ~/.codex/config.toml:

[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"

Exportieren Sie den Schlüssel dann in der Shell, in der Codex gestartet wird:

export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth

Nicht-interaktiv codex exec

In codex exec (Skripten, CI) fragt Codex vor dem Aufruf von Tools nicht nach und überspringt Tools, die Daten verändern. Fügen Sie default_tools_approval_mode = "approve" unter [mcp_servers.nexcmp] hinzu, damit diese aufgerufen werden können; das Panel gibt nach wie vor eine Vorschau aus und fordert bei Aktionen bezüglich Geld, Sicherheit und Löschungen eine Bestätigung an. Überprüft mit Codex CLI 0.166 am 30/10/2026.

Gemini CLI

Hinzufügen zu ~/.gemini/settings.json:

{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}

Gemini CLI schaltet MCP-Server in Ordnern ab, denen es nicht vertraut. Starten Sie es in einem vertrauenswürdigen Ordner (oder vertrauen Sie dem Ordner, wenn es danach fragt), und prüfen Sie es mit gemini mcp list — dies zeigt nexcmp … Connected an. Sie können den Schlüssel mit "Authorization": "Bearer $NEXCMP_KEY" aus der Datei heraushalten. Überprüft mit Gemini CLI 0.66 am 30/10/2026.

Cursor

Hinzufügen zu ~/.cursor/mcp.json (oder .cursor/mcp.json in einem Projekt):

{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}

Schlüssel aus Konfigurationsdateien heraushalten

Sofern der Client dies unterstützt, lesen Sie den Schlüssel aus einer Umgebungsvariable ein, anstatt ihn in die Datei zu schreiben: Codex tut dies standardmäßig (bearer_token_env_var) und Cursor akzeptiert "Bearer ${env:NEXCMP_KEY}". Committen Sie niemals eine Datei, die einen Schlüssel enthält.

OpenAI Agents SDK (Python)

from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)

Ein vollständiger Durchlauf (überprüft mit openai-agents 0.24 am 30/10/2026 — ein Lesetool, gefolgt von einer Saldoänderung, die die Bestätigungsvorschau zurückgab und beim zweiten Aufruf mit confirm_token angewendet wurde):

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())

OpenAI Responses API

Übergeben Sie den Server als Tool vom Typ mcp. Belassen Sie require_approval auf always, damit Ihr Programm Sie vor jedem Aufruf fragt:

{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}

Alles andere (reines HTTP)

Ein Client ohne MCP kann dieselben Tools über HTTP aufrufen. GET /v1/admin/agent/tools listet sie auf, POST /v1/admin/agent/tools/<name> führt eines mit einem JSON-Body von Argumenten aus und GET /v1/admin/openapi.json gibt eine OpenAPI-3.1-Beschreibung zurück (jedes Tool entspricht einer Operation). Alle erfordern Authorization: Bearer ak_....

Verifizierung

1. Tools ohne Client auflisten:

   curl -s https://cloud.example.com/mcp/admin \
     -H "Authorization: Bearer ak_XXXX" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

   Die Antwort ist ein JSON-RPC-Ergebnis mit den Tools, die Ihre Scopes erlauben.

2. Fragen Sie Ihren Client „run system_health“. Dies gibt Warnungen, den Integritätsstatus der verbundenen Infrastruktur, Zahlungen, E-Mail, KI und den Lizenzstatus zurück.

3. Öffnen Sie API & AI agents › Activity: Die Aufrufe werden mit dem Client-Namen und mcp aufgelistet.

4. Auf dem Server gibt sudo nexcmp status eine Zeile „MCP admin“ aus, die ready anzeigt, wenn der Endpunkt antwortet (HTTP 401 ohne Schlüssel ist der gesunde Zustand).

Tools

Der Server stellt 58 Tools bereit. Ein Client sieht nur die Tools, die durch die Scopes seines Schlüssels erlaubt werden: Lesetools erfordern admin:read, Schreibtools erfordern ihren eigenen Scope. Schreibtools erhalten zudem ein optionales Argument confirm_token (siehe Confirmation). Argumente werden gegen das Schema jedes Tools geprüft: Unbekannte oder falsch eingegebene Argumente werden mit einer Meldung abgelehnt, die sie benennt.

Die Preise sind in USD angegeben: Planpreise in Dollar pro Stunde (hourly_usd), Kontostände in Cent. Secrets können festgelegt werden, werden jedoch niemals zurückgegeben.

Übersicht und Protokolle

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
system_health	Warnungen, die Aufmerksamkeit erfordern, Infrastrukturintegrität, Zahlungen, E-Mail, KI, Lizenz- und Update-Status.	admin:read	Nein	Nein
setup_checklist	Was konfiguriert ist und was noch verbleibt: Lizenz, Infrastruktur, Zone, OS-Templates, Pläne, Zahlungen, E-Mail, Branding, Rechtliches, Testbestellung.	admin:read	Nein	Nein
license_status	Lizenzstatus und ob eine neuere NexCMP-Version existiert.	admin:read	Nein	Nein
audit_search	Durchsuchen des Admin-Audit-Protokolls und des API-Schlüssel-Protokolls.	admin:read	Nein	Nein

Einstellungen, Branding, Rechtliches, Module

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
settings_get	Allgemeine Einstellungen lesen (keys filtert; ein abschließendes * gleicht ein Präfix ab).	admin:read	Nein	Nein
settings_update	Allgemeine Einstellungen über ein flaches values-Objekt ändern. Es werden nur von settings_get aufgelistete Schlüssel akzeptiert.	settings:write	Ja	Wenn ein Schlüssel Zahlungen, Anmeldesicherheit, seitenweite Schalter oder Preise berührt
branding_get	Markenname, Farbe, Anzeigewährung, Verkäufername, Logo- und Favicon-URLs.	admin:read	Nein	Nein
branding_update	Markennamen festlegen (bis zu 60 Zeichen), Farbe (#rrggbb), Anzeigewährung (usd oder vnd) und Verkäufername.	settings:write	Ja	Nein
branding_logo_set	Laden Sie ein helles oder dunkles Logo oder ein Favicon über eine https-URL oder als base64 hoch (PNG, JPEG, WEBP, ICO oder SVG, bis zu 512 KB).	settings:write	Ja	Nein
legal_get	Nutzungsbedingungen und Datenschutzrichtlinie (Englisch und Vietnamesisch) sowie die neutralen Standards.	admin:read	Nein	Nein
legal_update	Legen Sie die Bedingungen und den Datenschutztext fest (einfaches Markdown, kein HTML, jeweils bis zu 50 KB). Eine leere Zeichenfolge stellt den Standard wieder her.	settings:write	Ja	Nein
modules_get	Welche optionalen Module aktiviert sind und welche umgeschaltet werden können.	admin:read	Nein	Nein
module_set	Schalten Sie ein optionales Modul ein oder aus (key muss eines von settable sein).	settings:write	Ja	Nein

E-Mail und Benachrichtigungen

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
smtp_get	Einstellungen für ausgehende E-Mails (Passwort maskiert) und Warteschlangenstatus.	admin:read	Nein	Nein
smtp_configure	Legen Sie den SMTP-Server fest. Das Ändern von Host, Port oder Sicherheit erfordert die erneute Eingabe des Passworts.	settings:write (+ secrets:write für das Passwort)	Ja	Nein
smtp_test	Senden Sie eine echte Test-E-Mail mit den gespeicherten Einstellungen.	settings:write	Sendet eine E-Mail	Nein
telegram_get	Admin-Benachrichtigungskanäle (Chat-IDs; Bot-Token werden niemals zurückgegeben).	admin:read	Nein	Nein
telegram_configure	Fügen Sie den Telegram-Benachrichtigungskanal (Bot-Token und Chat-ID) hinzu oder aktualisieren Sie ihn und schalten Sie Admin-Benachrichtigungen ein oder aus.	settings:write (+ secrets:write für das Token)	Ja	Nein
telegram_test	Senden Sie eine Testnachricht an den Telegram-Kanal.	settings:write	Sendet eine Nachricht	Nein

Zahlungen und Währung

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
payments_get	Status von Stripe, PayPal, Krypto (USDT) und Banküberweisung sowie aktivierte Kanäle und Gebühren.	admin:read	Nein	Nein
payment_configure	Legen Sie die Anmeldedaten eines Gateways fest (stripe, paypal, crypto oder bank).	billing:write (+ secrets:write)	Ja	Immer
payment_test	Überprüfen Sie die gespeicherten Anmeldedaten eines Gateways beim Anbieter.	billing:write	Nein	Nein
currency_get	Anzeigewährung und USD-zu-VND-Kurs (automatisch oder manuell).	admin:read	Nein	Nein
currency_set	Legen Sie die Anzeigewährung und/oder einen manuellen Kurs fest (0 bedeutet automatisch, ansonsten 15000 bis 50000).	billing:write	Ja	Wenn Sie den manuellen Kurs ändern

Infrastruktur und Zonen

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
cloudstack_get	Gespeicherter CloudStack-Endpunkt sowie Zonen- und Netzwerk-IDs (Schlüssel maskiert).	admin:read	Nein	Nein
cloudstack_test	Testen Sie einen Endpunkt mit einem API-Schlüssel und -Geheimnis ohne Speichern; listet Zonen auf.	infra:write (+ secrets:write, da Sie die Schlüssel übergeben)	Nein	Nein
cloudstack_connect	Speichern Sie die CloudStack-Verbindung.	infra:write (+ secrets:write)	Ja	Immer
proxmox_list	Als Quellen hinzugefügte Proxmox VE-Cluster mit Integritätsstatus.	admin:read	Nein	Nein
proxmox_add	Fügen Sie einen Proxmox VE-Cluster mit einem API-Token (user@realm!tokenid) und dessen Geheimnis hinzu.	infra:write (+ secrets:write)	Ja	Nein
proxmox_test	Verbinden Sie sich über die ID mit einem Cluster; der erste Erfolg pinnt dessen TLS-Zertifikat fest.	infra:write	Ja	Nein
proxmox_attach_zone	Verkaufen Sie einen Proxmox-Cluster in einer bestehenden Zone, optional mit einem Knoten als Region.	infra:write	Ja	Nein
zones_list	Zonen (Standorte), die Kunden auswählen können.	admin:read	Nein	Nein
zone_create	Erstellen Sie eine Zone.	infra:write	Ja	Nein

Katalog und Tarife

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
templates_list	Betriebssystem-Templates, die Kunden installieren können.	admin:read	Nein	Nein
templates_sync	Importieren Sie Betriebssystem-Templates von CloudStack.	catalog:write	Ja	Nein
template_update	Aktivieren oder verbergen Sie ein Template, benennen Sie es um, legen Sie den Anmeldenutzer oder die Reihenfolge fest.	catalog:write	Ja	Nein
offerings_list	CloudStack-Serviceangebote (CPU, Arbeitsspeicher, Root-Disk), um Tarife daraus zu erstellen.	admin:read	Nein	Nein
plans_list	Tarife mit Preis pro Stunde und Monat, Größe, Zone und Anzahl der Server, die sie nutzen.	admin:read	Nein	Nein
plan_create	Erstellen Sie einen Tarif. Preis als hourly_usd. CloudStack-Tarife erfordern cs_offering_id; Proxmox-Tarife erfordern backend_id.	catalog:write	Ja	Nein
plan_update	Tarif umbenennen, ein- oder ausblenden, aktivieren oder deaktivieren oder den Preis anpassen. Grössenänderungen bei einem verwendeten Tarif erfordern eine Kopie.	catalog:write	Ja	Wenn sich der Preis ändert
plans_from_offerings	Erstellt eine Starter-Tariftabelle aus Angeboten (oder Proxmox-Größen) basierend auf Ihren Kosten und einer Marge in Prozent. Gibt eine Vorschau zurück; erneut aufrufen mit apply=true, um die Tarife zu erstellen.	catalog:write	Mit apply=true	Immer bei Anwendung
quota_defaults_get	Standard-Kundenlimits.	admin:read	Nein	Nein
quota_defaults_set	quota_*-Einstellungen ändern.	catalog:write	Ja	Nein
coupons_list	Rabatt- und Gutscheincode-Chargen.	admin:read	Nein	Nein
coupon_create	Eine Charge von Codes erstellen: geben Sie money (Nennwert in USD-Cents) oder percent (1 bis 100, mit maximalem Rabatt) ein.	catalog:write	Ja	Immer

Kunden und Reseller

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
customers_search	Kunden nach E-Mail, Name oder IP finden.	admin:read	Nein	Nein
customer_get	Konto, Guthaben, Server und letzte Abrechnung eines Kunden.	admin:read	Nein	Nein
customer_adjust_balance	Guthaben in USD-Cents hinzufügen (positiv) oder entfernen (negativ). Ein Grund ist erforderlich.	billing:write	Ja	Immer
customer_block	Einen Kunden sperren und optional seine Server stoppen. Ein Grund ist erforderlich.	customers:write	Ja	Immer
customer_unblock	Einen Kunden entsperren.	customers:write	Ja	Nein
resellers_list	Reseller mit Wallet und Status.	admin:read	Nein	Nein
reseller_get	Website, Wallet, Benutzer und Gateways eines Resellers.	admin:read	Nein	Nein

KI-Anbieter

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
ai_provider_get	Der OpenAI-kompatible Provider, der vom Kunden-AI Chat und AI Agent verwendet wird (Schlüssel maskiert).	admin:read	Nein	Nein
ai_provider_set	Provider festlegen: Basis-URL, Modell, API-Schlüssel, Fallback-Modelle, Reasoning-Aufwand, aktiviert.	ai:write (+ secrets:write für den Schlüssel)	Ja	Nein
ai_provider_test	Dem gespeicherten Provider eine Frage stellen, um zu prüfen, ob er funktioniert.	ai:write	Nein	Nein

Konfigurationsdateien

Tool	Funktion	Scope	Ändert Daten	Fragt Sie
config_export	Die Konfiguration als YAML exportieren (Geheimnisse werden zu secret://-Referenzen).	admin:read	Nein	Nein
config_plan	Eine YAML-Konfiguration mit dem Live-Panel vergleichen und auflisten, was sich ändern würde.	admin:read	Nein	Nein
config_apply	Eine YAML-Konfiguration Abschnitt für Abschnitt anwenden. Jede Änderung folgt den normalen Geltungsbereichs- und Bestätigungsregeln.	admin:read + der Geltungsbereich jeder Änderung	Ja	Pro Änderung

Siehe Configuration as code für das Dateiformat.

Prompts

Der Server bietet außerdem drei vorgefertigte Prompts, die Clients als Verknüpfungen anzeigen können:

Prompt	Argument	Was die KI ausgeführt werden soll
initial-setup	keine	Ruft setup_checklist auf, erklärt jeden offenen Schritt in einem Satz, fragt Sie nach den benötigten Informationen, führt den Schritt mit dem passenden Tool aus, zeigt eine Vorschau von Geld- oder Sicherheitsänderungen an und schließt mit system_health ab.
add-proxmox	endpoint (optional, https://host:8006)	Fragt nach dem API-Token, dann proxmox_add, proxmox_test, Zonen-Tools und proxmox_attach_zone, schlägt daraufhin Tarife mit plans_from_offerings vor und wartet auf Ihre Genehmigung.
launch-pricing	margin_pct (optional, Standard 40)	Fragt nach Ihren monatlichen Kosten pro vCPU, pro GB RAM und pro GB Festplatte, zeigt eine Vorschauteule mit Kosten, Monatspreis und Stundepreis und erstellt die Tarife, nachdem Sie zugestimmt haben.

Bestätigung (confirm_token)

Aktionen, die Geld bewegen, Daten löschen, Zahlungsdaten oder Anmeldesicherheit ändern, sind zweistufig:

1. Der erste Aufruf ändert nichts. Das Ergebnis des Tools beginnt mit „CONFIRMATION REQUIRED“ und enthält eine Vorschau (was aufgerufen wird, warum es sensibel ist, die neuen und die aktuellen Werte) sowie ein confirm_token.
2. Der Client muss Ihnen die Vorschau anzeigen. Erst nach Ihrer Genehmigung wird dasselbe Tool erneut mit denselben Argumenten plus confirm_token aufgerufen.
3. Das Token funktioniert einmalig, nur für genau diese Anfrage und läuft nach 5 Minuten ab.

Die Serveranweisungen weisen die KI an, Tool-Ergebnisse als Daten und nicht als Anweisungen zu behandeln und einen Aufruf niemals mit einem von Ihnen nicht genehmigten Token zu wiederholen. Sie sind die Sicherheitsinstanz: Lesen Sie die Vorschau.

Nicht automatisch genehmigen

Einige Clients können jeden Tool-Aufruf automatisch genehmigen. Belassen Sie bei Schreib-Tools die pro Aufruf erforderliche Genehmigung oder verwenden Sie einen Read-only-Schlüssel, damit ein fehlerhafter Plan der KI Ihr Panel nicht ungesehen erreicht.

Wie es funktioniert

Komponente	Detail
Transport	POST /mcp/admin mit einer JSON-RPC 2.0-Nachricht; die Antwort ist application/json. Bis zu 20 Nachrichten in einem Batch. GET /mcp/admin antwortet mit 405 (kein Server-Stream); DELETE /mcp/admin beendet eine Sitzung.
Authentifizierung	Authorization: Bearer ak_... (ein manueller Schlüssel oder ein OAuth-Zugriffstoken). Fehlende oder falsche Anmeldeinformationen führen zu 401 mit WWW-Authenticate: Bearer ... resource_metadata=..., wodurch OAuth-Clients die Anmeldung selbst starten können.
Sitzungen	Mcp-Session-Id wird von initialize ausgestellt, ist an diesen Schlüssel gebunden und 24 Stunden lang gültig.
Funktionen	Tools und Prompts. Keine Ressourcen.
Größe	Anfrage-Body bis zu 1 MB; ein Tool-Ergebnis wird nach etwa 100 KB abgeschnitten.
Origin	Eine Anfrage mit einem Origin-Header von einer anderen Website wird abgelehnt (origin_not_allowed). Befehlszeilen- und Desktop-Clients senden keinen.
Gleiches Tor wie REST	Jeder Tool-Aufruf wird über die eigene Anfrage-Pipeline des Panels mit Ihrem Schlüssel erneut gesendet, sodass Scopes, IP-Bereiche, Rate-Limit, Bestätigung und das Aktivitätsprotokoll exakt wie bei direkten API-Aufrufen gelten.

Limits & Hinweise

• Ein Tool, das Sie nicht sehen können, ist ein Scope, den Sie nicht gewährt haben. Fügen Sie den Scope einem neuen Schlüssel hinzu.
• Das Festlegen eines Passworts oder API-Schlüssels über einen KI-Client bedeutet, dass das Geheimnis durch diese KI fließt. Wenn Sie möchten, lassen Sie secrets:write deaktiviert und geben Sie Geheimnisse selbst im Admin-Bereich ein oder verwenden Sie das Feld Secret im AI Chat (AI Chat im Admin-Bereich) oder secret://-Referenzen (Configuration as code).
• Clients teilen keine Sitzungen: Jede Verbindung beginnt mit initialize.
• Widerrufen Sie den Schlüssel unter API & AI agents, um einen KI-Client sofort zu trennen.

Fehlerbehebung

Symptom	Ursache	Behebung
401 invalid_key	Falscher, abgeschnittener oder Nicht-Admin-Schlüssel (zum Beispiel ein vk_-Schlüssel)	Verwenden Sie einen ak_-Schlüssel.
401 key_expired oder key_revoked	Der Schlüssel ist abgelaufen oder wurde widerrufen	Erstellen Sie einen neuen Schlüssel.
403 ip_not_allowed	Ihre IP befindet sich außerhalb der IP-Bereiche des Schlüssels	Verbinden Sie sich von einer zulässigen IP aus.
403 origin_not_allowed	Eine Browserseite von einem anderen Origin hat den Endpunkt aufgerufen	Verwenden Sie einen Desktop- oder CLI-Client.
404 bei einer Anfrage mit Mcp-Session-Id	Die Sitzung gehört zu einem anderen Schlüssel oder ist abgelaufen	Senden Sie initialize erneut.
400 unsupported MCP-Protocol-Version	Der Client verwendet eine Version, die dem Server nicht bekannt ist	Aktualisieren Sie den Client; unterstützt: 2025-11-25, 2025-06-18, 2025-03-26.
Die Tool-Liste ist kurz	Schlüssel-Scopes	Erstellen Sie einen Schlüssel mit mehr Scopes.
insufficient_scope bei einem Aufruf	Ein Tool benötigt einen zweiten Scope, zum Beispiel secrets:write	Fügen Sie den Scope einem neuen Schlüssel hinzu.
429 rate_limited	Mehr Aufrufe pro Minute, als der Schlüssel erlaubt	Warten Sie auf Retry-After oder erhöhen Sie das Limit für einen neuen Schlüssel.
claude.ai oder ChatGPT kann keine Verbindung herstellen	Die URL ist aus dem Internet nicht erreichbar oder ein Proxy blockiert /mcp/admin oder /oauth-admin/	Überprüfen Sie DNS, TLS und den Reverse Proxy.

Alle Fehlercodes finden Sie unter Admin API keys.