MCP — AI-Zugang zur Plattform¶

Der API-MCP gibt AI-Assistenten in der IDE (Cursor, Claude Code, vergleichbare Clients) nur lesenden Zugriff auf Ihre Polycrate-Organisation: Workspaces, Cluster, Alerts, Logs, Metriken und Live-Kubernetes-Objekte.

Er ist nicht derselbe Server wie der lokale CLI-MCP und nicht der Assistant-Chat in der Web-UI.

Welchen MCP brauchen Sie?¶

	CLI-MCP	API-MCP (diese Seite)
Start	Lokal: `polycrate mcp`	Remote: `https://<ihre-api-host>/mcp`
Anmeldung	Keine Plattform-Anmeldung	API-Key im `Authorization`-Header
Inhalt	Hub-Blöcke, Docs, Schemas für `workspace.poly`	Live-Daten Ihrer Organisation auf der Plattform
Typische Frage	„Welchen Block nehme ich für Postgres?“	„Welche Alerts feuern in acme? Was steht im Cluster?“
Schreibt etwas?	Nein (nur Hub/Docs lesen)	Nein (nur Plattform lesen)

Beide Server können parallel in Cursor eingetragen werden — unter unterschiedlichen Namen.

Der Assistant in der Polycrate-UI ist ein eigener Chat mit Sitzung und Verbrauch. Er ersetzt den MCP nicht und umgekehrt.

→ Lokaler Hub-/Docs-MCP: MCP Server (CLI)

Was der API-MCP kann¶

Der Assistent kann in Ihrem Namen (mit den Rechten des API-Keys):

Objekte auflisten und einzeln anzeigen (Workspaces, Cluster, Alerts, …)
Logs (VictoriaLogs) und Metriken (VictoriaMetrics) abfragen — gleiches Scope wie polycrate logs / polycrate metrics
Kubernetes-Ressourcen lesen, die Sie im Cluster sehen dürfen (Deployments, Pods, Services, …)

Er kann nicht:

etwas anlegen, ändern oder löschen — auch nicht mit einem read_write-Key
Kubernetes Secrets lesen oder kubectl exec / Port-Forward nutzen
Credentials, Tokens oder Schlüsselmaterial anzeigen (werden entfernt oder maskiert)
als Monitoring-Agent auftreten (Agent-Tokens werden abgewiesen)

Anmelden¶

Der Browser-Login (SSO-Session) gilt nicht für MCP. Es braucht einen Bearer-Token.

Key	Wer legt an	Was der Assistent sieht
User API-Key	Profil → API-Keys	Dieselben Organisationen und Rechte wie der Benutzer
Organization API-Key	Organisation → Tab API Keys	Nur diese Organisation. `read` reicht.
System API-Key	Administration → System API Keys	Plattformweit (Super-Admin). Nur intern verwenden.

Agent-Tokens aus dem Endpoint-Monitoring funktionieren nicht.

Anlegen und Widerrufen: API-Keys & Authentifizierung

Empfehlung für Kunden

Für den Alltag einen Organization API-Key im Modus read. Der MCP schreibt ohnehin nicht; so bleibt der Key auch außerhalb der IDE ungefährlich.

Token nicht in Git

Den Key nur in der lokalen MCP-Config oder als Umgebungsvariable ablegen — nicht ins Repository.

In Cursor einrichten¶

API-Key anlegen und kopieren.
~/.cursor/mcp.json um einen zweiten Server ergänzen (den CLI-MCP können Sie behalten):

{
  "mcpServers": {
    "polycrate": {
      "command": "polycrate",
      "args": ["mcp"]
    },
    "polycrate-api": {
      "url": "https://api.acme.corp/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}

Cursor neu starten. Unter MCP-Tools sollten acht Werkzeuge von polycrate-api erscheinen.

Ersetzen Sie api.acme.corp durch Ihre API-URL (dieselbe Basis wie in ~/.polycrate/polycrate.yml unter api.url). Der Pfad ist immer /mcp.

Claude Code¶

{
  "mcpServers": {
    "polycrate-api": {
      "type": "http",
      "url": "https://api.acme.corp/mcp",
      "headers": {
        "Authorization": "Bearer <api-key>"
      }
    }
  }
}

Verbindung prüfen¶

Ohne Token antwortet GET https://<ihre-api-host>/mcp mit einem Health-Status (kein Geheimnis). Tool-Aufrufe brauchen den Header; fehlende oder Agent-Tokens liefern 401.

Was Kunden sehen¶

Jeder angemeldete Benutzer ohne Superuser-Recht — inklusive Ayedo-Mitarbeitenden ohne Superuser — sieht denselben Kundenkatalog. Die acht Tools sind dieselben wie für Superuser; es fehlen nur interne Objekttypen.

Bereich	Typen (Beispiele)
Organisation	Organisation, Workspace
Betrieb	Alert, Downtime, Wartung, Wartungsfenster, Incident, Aktivität
Kubernetes	Cluster, App, Volume, Controlplane, Worker-Pool, Addon
Infrastruktur	Host, Load-Balancer-Instanz, S3-Bucket
Netz & DNS	Endpoint, DNS-Zone, DNS-Record
Sicherung & Security	Backup, Backup-Zeitplan, Vulnerability Finding

Blöcke und Action-Runs im Workspace sind im Kundenkatalog nicht enthalten (nur Superuser).

Was Superuser zusätzlich sehen¶

Nur Konten mit Superuser / Super Admin. Ein Staff-Häkchen ohne Superuser reicht nicht — dann gilt der Kundenkatalog.

Zusätzlich u. a.: Regionen, S3-Cluster, Load-Balancer-Regionen, PoPs, Provider und Provider-Accounts, Blöcke und Action-Runs, Rollouts, Domains und Zertifikate, CVEs und Compliance-Reports, Notifications, Notizen und Projekte, Grafana-Dashboards und Datasources, IPAM, Billing/Pricing.

Systemkonfiguration (SystemConfig) ist über MCP nicht erreichbar.

Werkzeuge (für Admins)¶

Der Assistent wählt die Tools selbst. Für Support und Freigaben:

Tool	Zweck
`catalog`	Welche Objekttypen der Key sehen darf
`describe_type`	Welche Filter ein Typ akzeptiert — vor dem ersten `list`
`list` / `get`	Gefilterte Liste bzw. ein Objekt per ID
`query_logs` / `query_metrics`	LogsQL bzw. PromQL, Scope wie die CLI
`k8s_list_resources` / `k8s_get_resource`	Live-Objekte im Cluster, den der User sehen darf

IDs vs. Namen¶

list und get filtern Organisationen und Workspaces per UUID.
Logs und Metriken brauchen den Organisationsnamen (z. B. acme), optional Workspace- und Block-Namen — keine UUID.

Wenn der Assistent „unbekannter Typ“ meldet, liegt der Typ nicht im Katalog dieses Keys (Kunden-Key vs. Superuser).

Beispiel-Fragen¶

„Liste die Workspaces der Organisation acme.“

„Welche Alerts feuern gerade? Zeig Details zum ersten.“

„Logs der letzten vier Stunden für Organisation acme, Workspace shop-prod, Fehler.“

„Welche Deployments laufen im Cluster von shop-prod im Namespace default?“

Kubernetes-Secrets werden abgelehnt. Felder wie Tokens oder PEM-Schlüssel in anderen Objekten kommen maskiert zurück.

Sicherheit (Admin)¶

Nur lesen. Writes gehen nicht über MCP, unabhängig vom Key-Modus.
Kein Session-Cookie. MCP ist für Maschinen/IDE, nicht für den Browser-Tab.
Kein Agent-Token. Monitoring-Agents bleiben auf ihre Check-APIs beschränkt.
Kein Secret-Objekt. Kind Secret / SecretList ist gesperrt; data / stringData werden entfernt.
Tenant-Grenze. Organization API-Keys sehen nur die eigene Org; Cross-Tenant wird abgelehnt.
Redaction. Sensible Felder (Passwörter, Tokens, PEM, verschachtelte Org-/Workspace-Secrets) werden gekürzt oder entfernt.

Org-API-Keys dürfen Alerts listen (Lesen). Anlegen, Ändern und Löschen von Alerts bleibt Admin-Sache in der UI/API — nicht über MCP.

Fehlerbehebung¶

Symptom	Typische Ursache
401 / „not authenticated“	Key fehlt, Tippfehler, oder Agent-Token statt User/Org/System-Key
Tools erscheinen nicht	Cursor nicht neu gestartet; URL ohne `/mcp`; Client spricht SSE statt einer HTTP-Antwort
„Unknown type“	Typ ist Superuser-only oder Tippfehler — `catalog` fragen
Leere Listen	Key hat kein Recht auf diese Org; Filter mit UUID vs. Name vertauscht
K8s „Secret not allowed“	Absicht — Secrets sind gesperrt
Logs/Metriken-Fehler	Organisationsname verwenden, nicht die UUID; Upstream-Observability nicht erreichbar

Siehe auch¶

MCP Server (CLI) — Hub, Dokumentation, Schemas
API-Keys & Authentifizierung
Observability (Logs & Metriken)
Endpoint-Monitoring — Agent-Tokens (nicht für MCP)