MCP-Proxy-Addon#

Das MCP-Proxy-Addon ist ein sicheres Gateway und eine Vermittlungsschicht für Model-Context-Protocol-Server (MCP) in Runabot. Es ermöglicht KI-Agenten, Entwickler-Arbeitsumgebungen und autonomen Bots (wie OpenClaw, Codex, Claude Code oder VS Code), auf externe Werkzeuge und APIs zuzugreifen, ohne vertrauliche Zugangsdaten Dritter direkt in der Workload-Umgebung zu speichern.

Warum ein MCP-Proxy?#

In einer KI-Agentenumgebung birgt der direkte Zugriff auf Rohschlüssel von APIs oder unbeschränkte Netzwerk-Endpunkte erhebliche Sicherheitsrisiken. Der MCP-Proxy löst dies durch ein Zero-Trust-Modell:

• Trennung von Zugangsdaten: API-Schlüssel und Autorisierungs-Tokens für Upstream-Dienste werden ausschließlich im MCP-Proxy als Write-Only-Geheimnisse gespeichert. Die Bot-Laufzeitumgebung erhält lediglich ein abgegrenztes Proxy-Token.
• Werkzeug-Governance: Von Upstream-Servern bereitgestellte Werkzeuge (Tools) werden automatisch erkannt und können geprüft, unter Quarantäne gestellt oder blockiert werden, bevor ein Agent sie ausführen darf.
• Feingranulare Zugriffsprofile: Werkzeuge können in rollenspezifischen Profilen gebündelt werden (z. B. read-only-docs, github-issue-reviewer, database-analytics), um die Aufrufbefugnisse jedes Bots präzise einzugrenzen.
• Auditierung und Ratenbegrenzung: Alle Werkzeugaufrufe laufen über den Proxy und bieten vollständige Transparenz und Kontrolle über die Aktivitäten der Agenten.

Kernkonzepte#

Erste Schritte#

1. Zugriff auf das MCP-Proxy-Dashboard#

Jede installierte MCP-Proxy-Addon-Instanz bietet ein eigenes Web-Dashboard, das über Runabot Single Sign-On (SSO) geschützt ist. Sie erreichen es direkt über die Runabot-Benutzeroberfläche unter Addons → MCP Proxy → Dashboard öffnen.

Alternativ können Sie die Instanz über die Runabot-CLI verwalten:

runabot addon mcpproxy upstream list <addon-name>

2. Upstream-Server registrieren#

Um einen Upstream-MCP-Server anzubinden, tragen Sie ihn über das Web-Dashboard oder die CLI ein:

runabot addon mcpproxy upstream create <addon-name> documentation \
  --protocol streamable-http \
  --url https://mcp.docs.example.com/mcp

3. Werkzeuge prüfen und freigeben#

Nach der Verbindung erkennt der MCP-Proxy die verfügbaren Werkzeuge automatisch:

# Erkannte Werkzeuge auflisten
runabot addon mcpproxy tool list <addon-name> documentation

# Ein bestimmtes Werkzeug freigeben
runabot addon mcpproxy tool approve <addon-name> documentation search_docs

4. Zugriffsprofil anlegen#

Zugriffsprofile fassen freigegebene Werkzeuge in wiederverwendbaren Berechtigungsgruppen zusammen:

runabot addon mcpproxy profile create <addon-name> researcher \
  --upstream documentation \
  --tool documentation=search_docs

5. Profil einem Bot zuweisen#

Die Zuweisung eines Profils an einen Bot bewirkt automatisch:

1. Das Öffnen der Netzwerk-Firewall, sodass der Bot-Container das MCP-Proxy-Addon erreichen kann.
2. Die Erstellung eines dauerhaften verwalteten Tokens (runabot-<bot-id>).
3. Die Bereitstellung der Endpunkt-URL und des Tokens in der Umgebung des Bots.

runabot addon mcpproxy assign <addon-name> researcher <bot-id>

Der tatsächliche Zugriff des Bots kann jederzeit geprüft werden:

runabot addon mcpproxy access effective <addon-name> <bot-id>

Coding-Agenten in Bot-Workloads einbinden#

In Ihrer Bot-Workload (z. B. einer Linux-Workload mit Codex oder Claude Code) können Sie den MCP-Client direkt mit der MCP-Proxy-Instanz verbinden.

Beispiel: Codex-Konfiguration#

In ~/.codex/config.toml:

[mcp_servers.<addon-name>]
url = "https://<addon-name>-mcp-proxy.<domain>/mcp"
http_headers = { Authorization = "Bearer <token>" }

Standardmäßig werden das verwaltete Token und die Endpunkt-URL in /root/linux.env innerhalb des Bot-Containers als <addon_name>_api_key und <addon_name>_url bereitgestellt.

Eigene Zugriffstokens verwenden (Opt-Out-Verfahren)#

Anwendungsfall#

Standardmäßig verwaltet und erneuert Runabot automatisch ein permanentes Bot-Token (runabot-<bot-id>). Spezifische Sicherheitsrichtlinien oder Workflows erfordern jedoch mitunter abweichende Token-Eigenschaften:

• Feste Ablaufzeiten und Rotation: Durchsetzen einer strikten Gültigkeitsdauer (z. B. 7 oder 30 Tage) mit planmäßiger Rotation.
• Spezifische Berechtigungen: Beschränken eines Agenten auf reine Lesezugriffe (read), unabhängig von Profil-Synchronisierungen.
• Entwicklerbezogene Zugangsdaten: Nutzen individueller Tokens zum Testen von Werkzeugen oder für isolierte Evaluierungsaufgaben.

Da der Bot eine Autorisierung in der Netzwerk-Firewall benötigt, um mit dem Addon zu kommunizieren, muss der Bot dem Addon zugewiesen bleiben, während das Authentifizierungstoken ersetzt wird.

Schritt-für-Schritt-Anleitung#

1. Bot dem Addon-Profil zuweisen: Weisen Sie den Bot dem Profil zu, damit die Firewall den Netzwerkverkehr freigibt:

   runabot addon mcpproxy assign <addon-name> <profile-name> <bot-id>

2. Benutzerdefiniertes Token erstellen: Öffnen Sie im MCP-Proxy-Dashboard Tokens → Create Token oder führen Sie folgenden CLI-Befehl aus:

   runabot addon mcpproxy token create <addon-name> custom-team-token \
     --upstream documentation \
     --permission read \
     --expires-in 30d

   Speichern Sie das ausgegebene Token sicher ab (es wird nur einmalig angezeigt).

3. Verwaltetes Token widerrufen (Soft-Revoke): Suchen Sie im MCP-Proxy-Dashboard unter Tokens das verwaltete Token (runabot-<bot-id>) und klicken Sie auf Revoke (bzw. führen Sie einen regulären Widerruf durch).

   Führen Sie keine permanente Löschung durch (/permanent), sondern nutzen Sie den regulären Widerruf (Revoke).

   Sobald ein verwaltetes Token den Status revoked: true hat, interpretiert die Runabot-Abgleichslogik dies als bewusstes Benutzer-Opt-Out. Sie wird das Token weder reparieren noch neu erstellen. Die Firewall-Freigabe zwischen dem Bot und dem Addon bleibt weiterhin aktiv.

4. Agenten mit dem benutzerdefinierten Token konfigurieren: Passen Sie die Konfiguration Ihres Agenten (z. B. ~/.codex/config.toml oder entsprechende Umgebungsvariablen) an:

   [mcp_servers.<addon-name>]
   url = "https://<addon-name>-mcp-proxy.<domain>/mcp"
   http_headers = { Authorization = "Bearer mcp_agt_ihr_benutzerdefiniertes_token..." }

5. Automatische Token-Verwaltung wieder aktivieren: Möchten Sie zur automatischen Verwaltung zurückkehren, weisen Sie das Profil über Runabot erneut zu:

   runabot addon mcpproxy assign <addon-name> <profile-name> <bot-id>

   Dieser Orchestrierungsschritt hebt den Opt-Out-Zustand auf und stellt ein neues permanentes Token bereit.