MCP API

Alle MCP-Endpunkte erfordern API-Key-Authentifizierung (Authorization: Bearer {project_api_key}) und setzen zusätzlich eine Rollen-Schwelle durch. Editor: registrieren, scannen, Richtlinie erstellen. Admin: Server aktivieren / pausieren / ablehnen / löschen, Notfall-Stopp, ein Werkzeug-Urteil setzen, eine Richtlinie löschen.

Server

Server auflisten

GET /api/v1/mcp/servers

Gibt alle registrierten MCP-Server des Projekts samt Werkzeug-Anzahl zurück.

Server registrieren (Editor)

POST /api/v1/mcp/servers

{
  "name": "GitHub MCP Server",
  "server_url": "https://api.githubcopilot.com/mcp/",
  "connector_type": "custom",
  "description": "Optionale Beschreibung",
  "is_proxied": true
}

connector_type ist ein optionales freies Label (Standard custom). Neue Server starten in PENDING_APPROVAL; die Registrierung löst keinen Scan aus.

Server aktualisieren (Editor)

PATCH /api/v1/mcp/servers/{id}

Felder: name, description, auth_method, auth_config. Diese Route ist nur Metadaten — sie kann status nicht ändern. Statuswechsel laufen ausschließlich über die auditierten Lifecycle-Aktionen unten.

Server löschen (Admin)

DELETE /api/v1/mcp/servers/{id}

Kaskadiert auf die Werkzeuge und Richtlinien dieses Servers. Auditiert.

Lifecycle-Aktionen (Admin, auditiert)

Statuswechsel nur über diese dedizierten, admin-auditierten Routen:

POST /api/v1/mcp/servers/{id}/activate   # PENDING_APPROVAL → ACTIVE (genehmigen) oder BLOCKED → ACTIVE (fortsetzen)
POST /api/v1/mcp/servers/{id}/pause      # ACTIVE → BLOCKED
POST /api/v1/mcp/servers/{id}/reject     # PENDING_APPROVAL → entfernt

Die Aktivierung friert zudem für jedes Werkzeug des Servers den Genehmigungs-Anker ein (Name + Beschreibung + Eingabe-Schema). Jede Aktion schreibt einen Eintrag in den unveränderlichen Admin-Audit-Trail (nach OCSF für SIEM-Export gemappt).

Werkzeuge scannen (Editor)

POST /api/v1/mcp/servers/{id}/scan

Verbindet sich mit dem MCP-Server, entdeckt Werkzeuge, klassifiziert je Werkzeug das Risiko und seedet je Werkzeug ein Start-Urteil (LOW → ALLOW, MEDIUM → LOG_ONLY, HIGH/CRITICAL → REQUIRE_APPROVAL; kein DENY geseedet). Der Scan aktiviert den Server nicht.

Die Antwort spiegelt das Ergebnis ehrlich:

// erreicht und gescannt
{ "scanned": true, "tool_count": 12, "policies_bound": 2, "policies_seeded": 12, "server_status": "ACTIVE" }

// Ziel konnte nicht gescannt werden (weiterhin HTTP 200 — kein Palveron-5xx)
{ "scanned": false, "reason": "unreachable", "detail": "refused", "target": "https://…", "server_status": "ERROR" }

reason ∈ unreachable · bad_status · rpc_error · invalid_response. Eine verbotene (private/interne) URL wird mit 400 (Validierung) abgelehnt, nicht als Scan-Ergebnis.

Server-Werkzeuge auflisten

GET /api/v1/mcp/servers/{id}/tools

Jedes Werkzeug trägt risk_level, category, description_hash, das wirksame policy_action und is_auto_generated (auto-geseedet vs. von Ihnen gesetzt) sowie den Genehmigungs-Anker: approved_hash, approved_at und das abgeleitete matches_approved (true = unverändert seit Genehmigung, false = abgewichen, null = nie genehmigt).

Ein Werkzeug-Urteil setzen (Admin)

POST /api/v1/mcp/servers/{id}/tools/{tool_id}/verdict

{ "action": "LOG_ONLY", "reason": "Geprüft — nur Protokollieren ausreichend" }

Setzt (oder lockert) den einen serverweiten Urteils-Slot des Werkzeugs und kollabiert ihn auf die neue Aktion, sodass Lockern tatsächlich wirkt. Auditiert. Es gibt keinen Update-Endpunkt für Richtlinien — nutzen Sie diesen oder löschen + neu erstellen.

Registry (Katalog)

GET /api/v1/mcp/registry?q={suche}&frontable=true&cursor={registry_name}&limit=50

Gibt Palverons Spiegel des offiziellen MCP-Registrys zurück — den Katalog hinter dem 1-Klick-Connect-Ablauf. Jedes Element: registry_name, version, description, remote_url, frontable (hat ein nutzbares HTTP-Remote), website_url, registry_status sowie die Vertrauens-Signale registry_updated_at, published_at, repository_url. Die Antwort trägt items, einen optionalen Keyset-next_cursor (über registry_name) und total.

Proxy

Einen Tool-Aufruf weiterleiten

POST /api/v1/mcp/proxy/{server_id}

Akzeptiert jede JSON-RPC-2.0-Anfrage. Optional den Header X-Agent-Id mit einer registrierten Agent-ID (nackte CUID) senden, damit Aufrufe diesem Agenten zugeordnet werden — eine unbekannte ID wird als anonym behandelt. Für die Methode tools/call laufen folgende Prüfungen in dieser Reihenfolge:

1. Server aktiv — jeder Status außer ACTIVE wird abgelehnt (PENDING_APPROVAL → -32002, sonst -32001)
2. Upstream-Auth anhängen — kann die Server-Auth nicht angehängt werden, wird der Aufruf fail-closed abgelehnt (-32008)
3. Genehmigungs-Anker / Poisoning — für genehmigte Werkzeuge wird eine vom genehmigten Fingerabdruck abgewichene Oberfläche blockiert (-32002, APPROVED_FINGERPRINT_MISMATCH); nie genehmigte Werkzeuge fallen auf die Legacy-Poisoning-Prüfung zurück (-32002)
4. Richtlinien-Auswertung — DENY → -32003, REQUIRE_APPROVAL → -32004
5. Weiterleiten an den MCP-Server, dann Trace mit traceType: MCP_TOOL_CALL erzeugen

Nicht-tools/call-Methoden (initialize, tools/list) passieren ohne Richtlinien-Auswertung.

Fehlercodes:

Richtlinien

Richtlinien auflisten

GET /api/v1/mcp/policies

Richtlinie erstellen (Editor)

POST /api/v1/mcp/policies

{
  "action": "DENY",
  "mcp_tool_id": "clxyz...",
  "agent_id": "ckagent...",
  "reason": "Shell execution not allowed"
}

Alle Felder außer action sind optional (mcp_tool_id, agent_id, reason, conditions). Gültige Aktionen: ALLOW, LOG_ONLY, REQUIRE_APPROVAL, DENY — jeder andere Wert liefert 400 mit der erlaubten Menge. Es gibt keinen Update-Endpunkt; um das Urteil eines Werkzeugs zu ändern, nutzen Sie die Set-Verdict-Route oben.

Richtlinie löschen (Admin)

DELETE /api/v1/mcp/policies/{id}

Genehmigungen

Ausstehende auflisten

GET /api/v1/mcp/approvals

Gibt nur PENDING-Genehmigungen zurück, die noch nicht abgelaufen sind.

Entscheiden

POST /api/v1/mcp/approvals/{id}/decide

{ "approved": true, "comment": "Geprüft — einmaliger Zugriff gewährt" }

Eine Genehmigung ist einmalig und an die exakten Argumente gebunden, für die sie angefragt wurde: Die Freigabe speichert einen kanonischen Hash der Tool-Argumente, und nur ein Aufruf mit genau diesen Argumenten löst sie ein — einmal, dann ist sie verbraucht. Ein Aufruf mit anderen Argumenten passt nicht auf die Freigabe und eröffnet eine neue Freigabe-Anfrage.

Notfall-Stopp (Admin)

POST /api/v1/mcp/emergency-stop

{ "scope": "all", "reason": "Security incident" }

Scopes: all (alle Server blockieren), server (einen bestimmten Server blockieren, target_id erforderlich), agent (alle Werkzeuge eines Agenten sperren, target_id erforderlich). Lässt alle ausstehenden Genehmigungen verfallen. Admin-gated und als Flare-attestierter Audit-Trace festgehalten.