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, eine strengere Richtlinie erstellen. Admin: Server genehmigen / fortsetzen / pausieren / ablehnen / löschen, Werkzeuge zulassen, einen Server oder Agenten gezielt sperren, eine Werkzeugregel setzen, eine erlaubende Richtlinie erstellen, eine Richtlinie löschen.

Eine Ablehnung hat die Form {"error": {"code", "message", "request_id"}}; message ist englisch, maßgeblich ist code (siehe Ablehnungscodes).

Server

Server auflisten

GET /api/v1/mcp/servers

Gibt alle registrierten MCP-Server des Projekts zurück. Je Server:

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

Genehmigen ist eine Entscheidung über jedes Werkzeug und nur nach einem erfolgreichen Scan möglich. Der Rumpf nennt jedes Werkzeug des letzten erfolgreichen Scans genau einmal, mit Regel und dem current_fingerprint aus der Werkzeugliste; ein Server ohne Werkzeuge wird mit "tools": [] genehmigt:

{ "tools": [ { "tool_id": "clxyz...", "rule": "REQUIRE_APPROVAL", "fingerprint": "5f0c7e…" } ] }

rule ∈ ALLOW · LOG_ONLY · REQUIRE_APPROVAL · DENY. In einem Schritt wird der Server aktiv und jedes Werkzeug mit seiner Regel zugelassen: die Regel gilt als von diesem Admin bestätigt (is_auto_generated: false), der Stand des Werkzeugs (Name, Beschreibung, Eingabe-Schema) wird festgehalten. Antwort: {"id", "status": "ACTIVE", "release": {"release_id", "released": [{"tool_id", "tool_name", "rule", "approved_hash"}]}}.

Fortsetzen nimmt keine Werkzeuge ({}) und lässt nichts zu: Ein seit der Zulassung geändertes Werkzeug bleibt gesperrt. Jede Aktion schreibt einen Eintrag in das manipulationserkennende Protokoll der Admin-Aktionen (nach OCSF für SIEM-Export gemappt).

Werkzeuge zulassen (Admin)

POST /api/v1/mcp/servers/{id}/tools/release

Nur auf einem ACTIVE Server. Der Rumpf hat dieselbe Form wie bei der Genehmigung und nennt mindestens ein Werkzeug, das nicht zugelassen (matches_approved: null) oder seit der Zulassung geändert ist (matches_approved: false). Das ist auch der Weg, ein geändertes Werkzeug erneut zuzulassen. Antwort: {"release_id", "released": […]}. Je Werkzeug entsteht ein Protokolleintrag MCP_TOOL_RELEASED.

Werkzeuge scannen (Editor)

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

Verbindet sich mit dem MCP-Server, entdeckt Werkzeuge, bestimmt je Werkzeug Aktion und Risiko und merkt sich den aktuellen Stand jedes Werkzeugs. Der Scan setzt keine Regel, lässt kein Werkzeug zu und ändert den Status nie.

Die Antwort spiegelt das Ergebnis ehrlich:

// erreicht und gescannt
{ "scanned": true, "tool_count": 12, "tools_new": 2, "tools_vanished": 0, "poisoning_suspects": 0, "policies_bound": 0, "tools_unreleased": 12, "server_status": "PENDING_APPROVAL" }

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

tools_unreleased ist die Zahl der Werkzeuge, die nichts bedienen, bis ein Admin sie zulässt; server_status ist der unveränderte Status. reason ∈ unreachable · bad_status · rpc_error · invalid_response; die Serverliste zeigt danach scan_state: failed. Kann der Scan an der Konfiguration nicht laufen (private oder interne Adresse, nicht unterstützte Anmeldeart, fehlendes Token), antwortet die Route mit 400 (Validierung) und hält scan_state: not_run mit Grund fest.

Server-Werkzeuge auflisten

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

Jedes Werkzeug trägt risk_level, category, description_hash, action, die wirksame serverweite Regel policy_action (null = keine Regel, Aufrufe werden zur Freigabe vorgelegt) und is_auto_generated (true = vom System angelegt, false = von einem Admin bestätigt) sowie die Zulassung:

„Vorschläge übernehmen" ist genau tools = [{tool_id: id, rule: proposed_rule, fingerprint: current_fingerprint}].

Eine Werkzeugregel setzen (Admin)

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

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

Setzt (oder lockert) die serverweite Regel des Werkzeugs und ersetzt dabei dessen serverweite Regeln durch die neue, sodass Lockern tatsächlich wirkt. Lässt nichts zu: Für ein nicht zugelassenes oder geändertes Werkzeug ist der Weg …/tools/release. Wird protokolliert. Es gibt keinen Update-Endpunkt für Richtlinien; nutzen Sie diese Route, oder löschen Sie und legen Sie neu an.

Vorlagen

GET /api/v1/mcp/templates

Listet die von Palveron gepflegten Vorlagen mit id, name, description, category, connector_type, auth_method, default_policies sowie available und unavailable_reason. Derzeit sind alle Vorlagen gesperrt (available: false, unavailable_reason: "auth_method_unsupported"): Sie melden sich mit einer Anmeldeart an, die das Gateway noch nicht unterstützt. Gesperrte Vorlagen bleiben gelistet; POST /api/v1/mcp/servers/from-template lehnt sie mit 409 mcp_template_unavailable ab und legt nichts an.

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. Agent gesperrt: ein gesperrter Agent wird zuerst abgewiesen (-32003, AGENT_EMERGENCY_STOP)
2. Server aktiv: PENDING_APPROVAL → -32002, pausiert (BLOCKED) → -32001
3. Zulassung: ein seit der Zulassung geändertes Werkzeug (-32002, APPROVED_FINGERPRINT_MISMATCH) und ein nicht zugelassenes Werkzeug (-32002, TOOL_NOT_RELEASED) werden gesperrt; ein nicht zugelassenes Werkzeug mit seit dem letzten Scan geänderter Beschreibung trägt den Legacy-Poisoning-Grund (-32002)
4. Regeln: die strengste Regel gewinnt (siehe Tool-Richtlinien): DENY → -32003, REQUIRE_APPROVAL → -32004, keine Regel → -32004 (NO_TOOL_RULE_REQUIRE_APPROVAL); das Berechtigungsmodell des Agenten kann zusätzlich verschärfen
5. Upstream-Auth anhängen: kann die Server-Auth nicht angehängt werden, wird der Aufruf fail-closed abgelehnt (-32008)
6. Weiterleiten an den MCP-Server, dann den Aufruf mit traceType: MCP_TOOL_CALL festhalten

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

Fehlercodes:

Richtlinien

Richtlinien auflisten

GET /api/v1/mcp/policies

Richtlinie erstellen (Editor, erlaubend: Admin)

POST /api/v1/mcp/policies

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

action ist Pflicht, dazu mindestens mcp_tool_id oder agent_id; optional reason, conditions. Gültige Aktionen: ALLOW, LOG_ONLY, REQUIRE_APPROVAL, DENY; jeder andere Wert liefert 400 mit der erlaubten Menge. Eine erlaubende Richtlinie (ALLOW, LOG_ONLY) verlangt einen Admin. Mit agent_id sind nur REQUIRE_APPROVAL und DENY erlaubt, weil eine Agentenregel die serverweite Regel nur verschärfen kann; ALLOW oder LOG_ONLY liefert 400 mcp_agent_rule_ineffective und schreibt nichts. Es gibt keinen Update-Endpunkt; um die Regel eines Werkzeugs zu ändern, nutzen Sie die Route „Werkzeugregel setzen" oben.

Richtlinie löschen (Admin)

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

Freigabeanfragen

Offene auflisten

GET /api/v1/mcp/approvals

Gibt nur offene Freigabeanfragen (PENDING) zurück, die noch nicht abgelaufen sind.

Entscheiden

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

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

Nach einer Freigabe senden Sie den Aufruf erneut und führen die Freigabe-Kennung mit, entweder im Kopf X-Palveron-Approval-Id oder im Argument _palveron_approval_id. Die Freigabe gilt einmalig und nur für genau die Argumente, für die sie angefragt wurde (ein kanonischer Hash der Tool-Argumente); ein Aufruf mit anderen Argumenten eröffnet eine neue Freigabe-Anfrage.

Gezielter MCP-Stopp (Admin)

POST /api/v1/mcp/emergency-stop

{ "scope": "server", "target_id": "<server_id>", "reason": "Security incident" }

Scopes: server (einen bestimmten Server blockieren, target_id erforderlich; ein nicht ACTIVE Server bleibt unverändert) und agent (die offenen Freigaben eines Agenten beenden, target_id erforderlich). Jeder beendet nur die offenen Freigaben seines Ziels. Nur für Admins und als Flare-bestätigter Protokolleintrag festgehalten. Das frühere scope: "all" entfällt (mcp_scope_all_removed); um das ganze Projekt auf einmal zu stoppen, nutzen Sie die Notabschaltung des Projekts.

Ablehnungscodes

Bei jedem dieser Codes ist nichts geschrieben.