Shared MCP Gateway

Fasst mehrere gemeinsam genutzte MCP-Server in einem HTTP-Gateway zusammen und bietet eine stabile, beobachtbare und wiederverwendbare MCP-Zugriffsschicht, die von Clients wie Codex, OpenCode, Claude Code, OpenClaw usw. gemeinsam genutzt werden kann.

Gelöste Probleme

In Szenarien, in denen mehrere Clients und mehrere MCP-Server parallel verwendet werden, treten häufig folgende Probleme auf:

• Jeder Client muss eine eigene MCP-Konfiguration pflegen, was zu redundanter Arbeit führt.

• Die Konfiguration derselben Toolchain ist über verschiedene Clients hinweg inkonsistent, was dazu führt, dass sie in einem Client funktioniert und im anderen nicht.

• Wenn ein nachgelagerter MCP-Server ausfällt, sind die Fehlerquellen verstreut, was eine einheitliche Protokollierung, Selbstprüfung und Fehlerisolierung erschwert.

• Das Hinzufügen oder Ersetzen eines MCP-Servers erfordert die manuelle Anpassung mehrerer Konfigurationsdateien, was die Änderungskosten erhöht.

Das Ziel von shared-mcp-gateway ist es, diese gemeinsam genutzten Funktionen zentral zu verwalten:

• Zentrale Registrierung: Verwaltung der nachgelagerten MCPs über registry.toml / registry.compose.toml.

• Zentraler Zugriffspunkt: Aggregation mehrerer nachgelagerter Dienste über einen einzigen HTTP-MCP-Endpunkt.

• Zentrales Betriebsmanagement: Einheitliche Gesundheitsprüfungen, strukturierte Protokollierung, Fehlerisolierung und Circuit-Breaking.

• Zentrale Konfigurationsgenerierung: Automatische Erstellung von Zugriffskonfigurationsfragmenten für Codex / OpenCode / OpenClaw.

Related MCP server: MCPHubs

Funktionen

Das Projekt unterstützt derzeit:

• Aggregation mehrerer stdio-basierter nachgelagerter MCP-Server.

• Einheitliche Bereitstellung nachgelagerter Tools im Format namespace.tool_name.

• Automatisches Hinzufügen von caller-Kennungen für verschiedene Clients zur einfachen Protokollverfolgung.

• Bereitstellung einer /healthz-Schnittstelle zur Gesundheitsprüfung, um verbundene Dienste, ausgefallene Dienste und den Status des Circuit-Breakers zu überwachen.

• Bereitstellung strukturierter logfmt-Protokolle für die einfache Suche in Systemen wie grep, CLS, Loki usw.

• Minimale Isolierung bei Ausfällen nachgelagerter Dienste, um zu verhindern, dass ein einzelner MCP-Server die gesamte Erfahrung beeinträchtigt.

• Generierung von Client-Konfigurationsdateien:

  • Codex: generated/codex-mcp.toml

  • OpenCode: generated/opencode-mcp.jsonc

  • OpenClaw: generated/openclaw-mcp.json

• Konnektivitäts-, Tool- und Kapazitätsprüfungen über scripts/self_check.py.

Anwendungsfälle

Direkt geeignet für folgende Szenarien:

• Dieselben MCP-Funktionen müssen von mehreren KI-Clients wiederverwendet werden.

• Trennung von "gemeinsam genutzten Funktionen" und "lokalen, host-spezifischen Funktionen".

• Bedarf an einheitlicher Protokollierung, Selbstprüfung, Gesundheitsprüfung und Fehlerisolierung.

• Wunsch, bei der Hinzufügung eines neuen gemeinsamen MCP nur eine einzige Registrierungskonfiguration ändern zu müssen.

Projektstruktur

shared-mcp-gateway/
├── Dockerfile                          # 网关镜像构建文件
├── docker-compose.yml                  # 当前本地落地用 Compose 编排
├── registry.toml                       # 宿主机直跑配置
├── registry.compose.toml               # 容器内运行配置
├── requirements.txt                    # Python 依赖
├── docs/
│   └── mcp-topology.md                 # 哪些 MCP 进入网关、哪些保留本地特例
├── generated/                          # 自动生成的客户端配置文件
├── templates/                          # 可复制的配置模板
│   ├── docker-compose.template.yml     # Compose 配置模板
│   ├── registry.compose.template.toml  # 容器内注册表模板
│   └── registry.template.toml          # 宿主机注册表模板
├── scripts/
│   ├── render_client_configs.py        # 生成客户端配置片段
│   └── self_check.py                   # 健康检查与关键工具自检
├── shared_mcp_gateway/
│   ├── config.py                       # 注册表解析
│   ├── gateway.py                      # HTTP MCP 聚合网关主程序
│   ├── logging_utils.py                # 结构化日志输出
│   ├── render.py                       # 客户端配置渲染
│   └── stdio_bridge.py                 # stdio 客户端到 HTTP MCP 的桥接

Kernarbeitsweise

flowchart LR
    A["Codex / OpenCode / OpenClaw"] --> B["stdio_bridge / HTTP Client"]
    B --> C["Shared MCP Gateway"]
    C --> D["mempalace"]
    C --> E["mysql-db"]
    C --> F["obsidian-kb"]
    C --> G["tencent-cls"]

Erläuterung des Anforderungsablaufs

Nachdem eine MCP-Anfrage das Shared Gateway erreicht hat, folgt sie diesem Pfad:

1. Der Client greift über stdio_bridge.py oder direkt über HTTP auf das Shared Gateway zu.

2. RequestLoggingMiddleware injiziert caller, request_id und den Kontext der Zugriffsprotokollierung.

3. SharedMcpGateway lokalisiert das Ziel basierend auf Toolname / Ressourcen-URI / Prompt-Name.

4. Wenn das Ziel bereits durch den Circuit-Breaker blockiert ist, wird die Anfrage sofort abgelehnt, um eine Überlastung fehlerhafter Dienste zu vermeiden.

5. Wenn die Weiterleitung erlaubt ist, gelangt die Anfrage zu DownstreamConnection und greift über eine Single-Session-Sperre seriell auf den nachgelagerten MCP zu.

6. Nach Abschluss des Aufrufs werden Metriken, Fehlerzähler und der Circuit-Breaker aktualisiert und mit heartbeat / healthz synchronisiert.

Empfohlene Aufteilung der Kernmodule:

• shared_mcp_gateway/config.py: Registrierungs-Parsing und stark typisierte Konfigurationsobjekte.

• shared_mcp_gateway/gateway.py: Einheitliche Indizierung, Anforderungsweiterleitung, Fehlerisolierung, Gesundheitsprüfung, Heartbeat-Protokollierung.

• shared_mcp_gateway/stdio_bridge.py: Bereitstellung einer HTTP-Gateway-Brückenschicht für Clients, die nur stdio unterstützen.

• shared_mcp_gateway/render.py: Rendern der einheitlichen Registrierung in Client-spezifische Zugriffskonfigurationen.

• scripts/self_check.py: Konnektivitätsprüfung über Gesundheits-Schnittstellen und echte MCP-Aufrufe.

Sequenzdiagramm der Anfrage

Das folgende Diagramm hilft beim Verständnis des mentalen Modells beim Lesen des Codes:

sequenceDiagram
    participant Client as "MCP Client"
    participant Bridge as "stdio_bridge / HTTP Client"
    participant Middleware as "RequestLoggingMiddleware"
    participant Gateway as "SharedMcpGateway"
    participant Breaker as "CircuitBreaker"
    participant Downstream as "DownstreamConnection"
    participant Server as "Downstream MCP Server"

    Client->>Bridge: 发起 list_tools / call_tool / read_resource
    Bridge->>Middleware: HTTP 请求进入网关
    Middleware->>Gateway: 注入 caller / request_id 后转发
    Gateway->>Breaker: 检查目标下游是否允许访问
    alt breaker open
        Breaker-->>Gateway: reject
        Gateway-->>Client: 快速失败 / 返回熔断提示
    else breaker closed
        Gateway->>Downstream: 按 namespace 路由请求
        Downstream->>Server: 串行发起 MCP 调用
        Server-->>Downstream: 返回结果或异常
        Downstream-->>Gateway: 返回标准 MCP 响应
        Gateway->>Gateway: 更新 metrics / failure streak / breaker
        Gateway-->>Client: 返回聚合后的 MCP 响应
    end

Empfehlungen zum Lesen des Codes

Um den Hauptablauf schnell zu verstehen, wird folgende Reihenfolge empfohlen:

1. shared_mcp_gateway/config.py: Verständnis der Registrierungsstruktur.

2. shared_mcp_gateway/render.py: Verständnis der Generierung von Client-Zugriffskonfigurationen.

3. shared_mcp_gateway/stdio_bridge.py: Verständnis der Anbindung von stdio-Clients an das HTTP-Gateway.

4. shared_mcp_gateway/gateway.py: Fokus auf SharedMcpGateway, DownstreamConnection, RequestLoggingMiddleware.

5. scripts/self_check.py: Verständnis der Überprüfung der "Live-Schnittstellen" und "echten Fähigkeiten" nach dem Deployment.

Erste Schritte

1. Abhängigkeiten installieren

cd /path/to/shared-mcp-gateway
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Konfiguration vorbereiten

Sie können sich direkt an den Vorlagendateien orientieren:

• templates/registry.template.toml

• templates/registry.compose.template.toml

• templates/docker-compose.template.yml

Die gängigste Vorgehensweise ist:

cp templates/registry.template.toml registry.local.toml
cp templates/registry.compose.template.toml registry.compose.local.toml
cp templates/docker-compose.template.yml docker-compose.local.yml

Ersetzen Sie dann die Pfade, Ports und Befehle für nachgelagerte Dienste in den Vorlagen durch Ihre tatsächliche Umgebung.

3. Lokaler Start

python3 shared_mcp_gateway/gateway.py --registry registry.toml --log-level INFO

Nach dem Start sind folgende Endpunkte verfügbar:

• MCP-Endpunkt: http://127.0.0.1:8787/mcp

• Gesundheitsprüfung: http://127.0.0.1:8787/healthz

4. Start mit Docker Compose

docker compose up -d --build
docker compose ps
curl http://127.0.0.1:8787/healthz

Stoppen:

docker compose down

Konfiguration: Kernkonfiguration

Die zentrale Konfigurationsdatei des Projekts ist registry.toml, die hauptsächlich aus fünf Teilen besteht:

1. Listener-Konfiguration

[listen]
host = "127.0.0.1"
port = 8787
path = "/mcp"

Bedeutung:

• host: Host-Adresse des Gateways

• port: Port des Gateways

• path: HTTP-Pfad für MCP

2. Gateway-Metadaten

[gateway]
name = "shared-gateway"
namespace_separator = "."
description = "Shared MCP gateway for Codex, OpenCode and OpenClaw."

Bedeutung:

• name: Name des nach außen exponierten Gateways

• namespace_separator: Trennzeichen für Namespaces, standardmäßig .

• description: Beschreibung des Gateways

3. Konfiguration nachgelagerter MCP-Server

[[servers]]
key = "mysql-db"
enabled = true
namespace = "mysql_db"
command = "/bin/bash"
args = ["-lc", "cd /opt/mcps/mysql-connector && ./.venv/bin/python server.py"]

Bedeutung:

• key: Eindeutige Kennung des nachgelagerten Dienstes

• enabled: Aktiviert oder nicht

• namespace: Namespace-Präfix für Toolnamen

• command: Startbefehl

• args: Startargumente

• env: Optional, zur Injektion von Umgebungsvariablen für diesen Dienst

4. Lokale Ausnahmen

[local_exceptions.openclaw]
keep_local = ["openspace"]
reason = "OpenSpace 强依赖宿主上下文，保留本地直连。"
endpoint = "http://127.0.0.1:8081/mcp"

Zur Dokumentation, welche Funktionen nicht über das Shared Gateway laufen, sondern lokal direkt verbunden bleiben.

5. Metadaten für Client-Konfigurationspfade (optional)

[clients.codex]
config_path = "~/.codex/config.toml"

Bedeutung:

• clients.* dient hauptsächlich zur Dokumentation der Speicherorte der Client-Konfigurationsdateien.

• Das Projekt schreibt diese Pfade standardmäßig nicht automatisch zurück.

• Es wird empfohlen, zuerst scripts/render_client_configs.py auszuführen und die Ergebnisse manuell in die Client-Konfigurationen zu kopieren.

Konfiguration: Beispiele

Beispiel 1: Konfiguration für den Host-Betrieb

Hier ist ein minimales Beispiel zur direkten Verwendung:

[listen]
host = "127.0.0.1"
port = 8787
path = "/mcp"

[gateway]
name = "shared-gateway"
namespace_separator = "."
description = "Shared MCP gateway for local development."

[[servers]]
key = "mempalace"
enabled = true
namespace = "mempalace"
command = "/opt/mempalace/.venv/bin/python"
args = ["-m", "mempalace.mcp_server"]
env = { PYTHONPATH = "/opt/mempalace" }

[[servers]]
key = "mysql-db"
enabled = true
namespace = "mysql_db"
command = "/bin/bash"
args = ["-lc", "cd /opt/mcps/mysql-connector && ./.venv/bin/python server.py"]

[local_exceptions.shared_gateway]
managed = ["mempalace", "mysql_db"]
reason = "共享能力统一由 shared-gateway 纳管。"

Beispiel 2: Ansatz für Docker Compose

Wenn Sie das Gateway einheitlich in einem Container betreiben möchten, orientieren Sie sich an folgendem Ansatz:

services:
  shared-mcp-gateway:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: shared-mcp-gateway
    restart: unless-stopped
    ports:
      - "127.0.0.1:8787:8787"
    environment:
      OBSIDIAN_VAULT_PATH: /workspace/openclaw-workspace
      PYTHONPATH: /workspace/mempalace
    volumes:
      - /opt/mcps:/workspace/mcps:ro
      - /opt/mempalace:/workspace/mempalace:ro
      - /opt/openclaw-workspace:/workspace/openclaw-workspace:rw
      - /opt/mempalace-data:/root/.mempalace:rw

Geeignet für:

• Zusammenführung mehrerer MCP-Laufzeitabhängigkeiten im selben Container-Kontext.

• Sicherstellung stabiler Verzeichnisse für nachgelagerten Code durch Read-Only-Mounts.

• Einheitliche Verwendung von registry.compose.toml innerhalb des Containers.

Konfigurationsvorlagen

Um den Einstieg zu erleichtern, enthält das Projekt kopierbare Vorlagendateien:

1. Registrierungsvorlage

Datei: templates/registry.template.toml

Verwendung:

• Bei der Initialisierung einer neuen Umgebung einfach kopieren und Pfade anpassen.

• Geeignet als Startpunkt für den Betrieb auf dem Host.

• Enthält die vollständige Struktur von listen, gateway, servers, clients und local_exceptions.

Empfohlene Vorgehensweise:

cp templates/registry.template.toml registry.local.toml

2. Registrierungsvorlage für Container

Datei: templates/registry.compose.template.toml

Verwendung:

• Bietet eine Vorlage mit Pfaden innerhalb des Containers für Docker / Compose-Szenarien.

• Vermeidet die Übernahme absoluter Host-Pfade in die Container-Konfiguration.

• Geeignet als kopierbarer Startpunkt für registry.compose.toml.

Empfohlene Vorgehensweise:

cp templates/registry.compose.template.toml registry.compose.local.toml

3. Compose-Vorlage

Datei: templates/docker-compose.template.yml

Verwendung:

• Schnelle Vorbereitung der Compose-Orchestrierung auf neuen Maschinen oder Umgebungen.

• Vermeidet die direkte Änderung der produktiven oder maschinenspezifischen docker-compose.yml.

• Erleichtert die Anpassung von Mount-Pfaden und Umgebungsvariablen an eigene Standards.

Empfohlene Vorgehensweise:

cp templates/docker-compose.template.yml docker-compose.local.yml

Beispiele für die Client-Anbindung

Empfohlener Ablauf:

1. Starten Sie das shared-gateway und bestätigen Sie, dass http://127.0.0.1:8787/healthz funktioniert.

2. Führen Sie python3 scripts/render_client_configs.py aus, um die Client-Konfigurationsfragmente für die aktuelle Umgebung zu generieren.

3. Kopieren Sie bevorzugt die tatsächlichen Ergebnisse aus dem Verzeichnis generated/, anstatt umgebungsspezifische Pfade manuell zu schreiben.

Codex-Anbindung

Es wird empfohlen, direkt generated/codex-mcp.toml zu verwenden. Die Struktur sieht in etwa so aus:

[mcp_servers.shared-gateway]
command = "/bin/bash"
args = ["-lc", "python3 /absolute/path/to/shared_mcp_gateway/stdio_bridge.py --url http://127.0.0.1:8787/mcp --caller codex"]
enabled = true

OpenCode-Anbindung

Es wird empfohlen, direkt generated/opencode-mcp.jsonc zu verwenden. Die Struktur sieht in etwa so aus:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shared-gateway": {
      "type": "local",
      "enabled": true,
      "command": [
        "/bin/bash",
        "-lc",
        "python3 /absolute/path/to/shared_mcp_gateway/stdio_bridge.py --url http://127.0.0.1:8787/mcp --caller opencode"
      ]
    }
  }
}

OpenClaw-Anbindung

OpenClaw kann direkt über HTTP MCP laufen. Es wird empfohlen, generated/openclaw-mcp.json zu verwenden:

{
  "mcpServers": {
    "shared-gateway": {
      "url": "http://127.0.0.1:8787/mcp",
      "transport": "streamable-http",
      "connectionTimeoutMs": 10000,
      "disabled": false
    }
  }
}

Claude Code-Anbindung

Das Projekt unterstützt derzeit die Injektion von Caller-IDs für claude-code über stdio_bridge.py. Der Kernansatz besteht darin, die Bridge als lokalen stdio-MCP-Befehl zu verwenden:

python3 /absolute/path/to/shared_mcp_gateway/stdio_bridge.py --url http://127.0.0.1:8787/mcp --caller claude-code

Wenn Ihre Client-Konfiguration benutzerdefinierte stdio-MCP-Befehle zulässt, können Sie diesen Bridge-Befehl einfach wiederverwenden.

Empfehlungen zur Konfigurationsumsetzung

Um Umgebungsprobleme zu minimieren, wird folgende Reihenfolge empfohlen:

1. Kopieren Sie zuerst die Vorlagendateien, ändern Sie nicht direkt die vorhandenen Beispiele im Projekt.

2. Stellen Sie sicher, dass jeder nachgelagerte MCP-Server einzeln gestartet werden kann.

3. Tragen Sie die nachgelagerten Dienste nacheinander in registry.toml oder registry.compose.toml ein.

4. Überprüfen Sie nach dem Start des Gateways zuerst /healthz und führen Sie dann scripts/self_check.py aus.

5. Führen Sie abschließend scripts/render_client_configs.py aus, um die Client-Konfigurationen zu synchronisieren.

Es wird empfohlen, drei Arten von Dateien zu unterscheiden:

• registry.toml: Konfiguration für den Host-Betrieb

• registry.compose.toml: Konfiguration für den Container-Betrieb

• templates/*.template.*: Vorlagen für die Initialisierung neuer Umgebungen

Häufige Befehle

Client-Konfiguration generieren

python3 scripts/render_client_configs.py

Dieses Skript:

• Liest registry.toml

• Generiert einheitlich Konfigurationsfragmente für Codex / OpenCode / OpenClaw

• Vermeidet Konfigurationsdrift beim manuellen Kopieren von Bridge-Startbefehlen

Die Ergebnisse befinden sich in:

• generated/codex-mcp.toml

• generated/opencode-mcp.jsonc

• generated/openclaw-mcp.json

Gesundheitsprüfung durchführen

python3 scripts/self_check.py
python3 scripts/self_check.py --json

Standardmäßig werden zwei Arten von Prüfungen durchgeführt:

• healthz: Überprüfung, ob das Gateway korrekt exponiert ist, ob nachgelagerte Dienste fehlen und ob der Circuit-Breaker ausgelöst wurde.

• gateway_tools: Verbindung zum Gateway als MCP-Client, um zu prüfen, ob wichtige Tools vorhanden sind, und Durchführung von Prüfungen ohne Nebenwirkungen.

Protokolle anzeigen

docker compose logs -f shared-mcp-gateway

Aktuell angebundene Shared MCPs

• mempalace

• mysql-db

• obsidian-kb

• tencent-cls

Informationen zur Topologie finden Sie unter: /path/to/shared-mcp-gateway/docs/mcp-topology.md

Empfehlungen für die Zukunft

Wenn Sie dieses Projekt weiter ausbauen möchten, wird folgende Reihenfolge empfohlen:

1. Fügen Sie in registry.toml ein neues [[servers]] hinzu.

2. Überprüfen Sie lokal, ob dieser MCP unabhängig gestartet werden kann.

3. Überprüfen Sie nach dem Start des Gateways /healthz.

4. Führen Sie scripts/self_check.py aus, um zu sehen, ob die Kernfunktionen normal funktionieren.

5. Führen Sie scripts/render_client_configs.py erneut aus, um die Client-Konfigurationen zu synchronisieren.

Wenn Sie aktuell Dokumentationen, Vorlagen oder Standardkonfigurationen in diesem Projekt ergänzen möchten, pflegen Sie bevorzugt:

• README.md

• templates/registry.template.toml

• templates/registry.compose.template.toml

• templates/docker-compose.template.yml

• docs/mcp-topology.md