---
title: Einen KI-Client verbinden (MCP)
description: Verbinden Sie Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, ChatGPT oder OpenAI SDKs mit dem admin MCP endpoint.
url: https://nexcmp.com/de/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Einen KI-Client verbinden (MCP) {#connect-an-ai-client-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 {#what-it-does}

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.

::: info Zwei MCP-Endpunkte
`/mcp` ist der **Kundenendpunkt** (Kunden-API-Schlüssel, `vk_`; siehe [MCP server](https://nexcmp.com/de/docs/developers/mcp/)). `/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 {#requirements}

| 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](https://nexcmp.com/de/docs/configure-with-ai/admin-api-keys/) (`ak_...`) mit den gewünschten Scopes **oder** die OAuth-Anmeldung für Web-Connectors ([OAuth connectors](https://nexcmp.com/de/docs/configure-with-ai/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 {#prepare-the-infrastructure}

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:

```bash
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 {#connect-in-nexcmp}

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](https://nexcmp.com/de/docs/configure-with-ai/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.

![Verbinden Sie einen AI-Tab mit der MCP-URL und einer Karte mit Kopier-Button pro Client](https://nexcmp.com/de/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
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 {#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:

```json
{
  "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) {#claude-ai-custom-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](https://nexcmp.com/de/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (Entwicklermodus) {#chatgpt-developer-mode}

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](https://nexcmp.com/de/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

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

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

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

::: tip 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 {#gemini-cli}

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

```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 {#cursor}

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

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

::: tip 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) {#openai-agents-sdk-python}

```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):

```python
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 {#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:

```json
{
  "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) {#anything-else-plain-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 {#verify}

1. Tools ohne Client auflisten:

   ```bash
   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 {#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](#confirmation-confirm-token)). 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 {#overview-and-logs}

| 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 {#settings-branding-legal-modules}

| 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 {#email-and-alerts}

| 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 {#payments-and-currency}

| 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 {#infrastructure-and-zones}

| 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 {#catalog-and-plans}

| 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 {#customers-and-resellers}

| 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 {#ai-provider}

| 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 {#configuration-files}

| 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](https://nexcmp.com/de/docs/configure-with-ai/config-as-code/) für das Dateiformat.

## Prompts {#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`) {#confirmation-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.

::: warning 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 {#how-it-works}

| 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 {#limits-notes}

- 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](https://nexcmp.com/de/docs/configure-with-ai/ai-chat-in-admin/#secrets)) oder `secret://`-Referenzen ([Configuration as code](https://nexcmp.com/de/docs/configure-with-ai/config-as-code/#secrets)).
- 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 {#troubleshooting}

| 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](https://nexcmp.com/de/docs/configure-with-ai/admin-api-keys/#errors).