Shared MCP Gateway

複数の共有型MCPサーバーを1つのHTTPゲートウェイに集約し、安定した観測可能で再利用可能なMCPアクセス層を外部に提供します。これにより、Codex、OpenCode、Claude Code、OpenClawなどのクライアントで共通利用が可能になります。

プロジェクトが解決する課題

複数のクライアントやMCPサーバーを並行して使用するシナリオでは、通常以下のような問題が発生します。

• 各クライアントで個別にMCP設定を管理する必要があり、重複作業が多い。

• 同じツールチェーンでもクライアントごとに設定が異なり、「このクライアントでは使えるが、あちらでは使えない」といった問題が発生しやすい。

• 下流のMCPサーバーで異常が発生した際、調査窓口が分散しており、ログの一元管理、自己診断、サーキットブレーカー処理が困難。

• MCPサーバーの追加や入れ替えのたびに複数の設定ファイルを修正する必要があり、変更コストが高い。

shared-mcp-gateway の目的は、これらの共有機能を一元管理することです。

• レジストリの一元管理：registry.toml / registry.compose.toml を通じて下流のMCPを一元管理。

• 機能の一元公開：1つのHTTP MCPエンドポイントを通じて複数の下流サービスを集約。

• 運用管理の一元化：ヘルスチェック、構造化ログ、障害隔離、最小限のサーキットブレーカーを統合。

• クライアント設定の自動生成：Codex / OpenCode / OpenClaw 用の接続設定スニペットを自動生成。

Related MCP server: MCPHubs

プロジェクトでできること

本プロジェクトは現在以下をサポートしています：

• 複数のstdioベースの下流MCPサーバーの集約。

• 下流ツールを namespace.tool_name 形式で統一的に公開。

• クライアントごとに caller 識別子を自動付与し、ログ追跡を容易化。

• /healthz ヘルスチェックインターフェースを提供し、接続済みサービス、失敗サービス、サーキットブレーカーの状態を確認可能。

• 構造化された logfmt ログを提供し、grep、CLS、Lokiなどのシステムでの検索を容易化。

• 下流で異常が発生した際に最小限の隔離を行い、単一のMCPサーバーの停止が全体に影響するのを防止。

• クライアント設定ファイルの生成：

  • Codex：generated/codex-mcp.toml

  • OpenCode：generated/opencode-mcp.jsonc

  • OpenClaw：generated/openclaw-mcp.json

• scripts/self_check.py を通じた接続性、自己診断ツール、主要機能の生存確認。

適用シナリオ

以下のようなシナリオでの利用に適しています：

• 同一のMCP機能を複数のAIクライアントで再利用したい場合。

• 「共有機能」と「ホスト固有の特殊機能」を階層的に管理したい場合。

• ログ、自己診断、ヘルスチェック、障害隔離を一元化したい場合。

• 新しい共有MCPを追加する際に、レジストリ設定を1箇所修正するだけで済ませたい場合。

プロジェクト構造

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 的桥接

コアとなる仕組み

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"]

実行フローの説明

MCPリクエストが共有ゲートウェイに入った後の主要なパスは以下の通りです：

1. クライアントが stdio_bridge.py を経由、または直接HTTPで共有ゲートウェイにアクセス。

2. RequestLoggingMiddleware が caller、request_id、アクセスログのコンテキストを注入。

3. SharedMcpGateway がツール名 / リソースURI / プロンプト名に基づいてターゲットの下流サービスを特定。

4. 対象の下流サービスがサーキットブレーカー状態であれば、リクエストは即座に拒否され、異常サービスへの継続的な負荷を回避。

5. 転送が許可される場合、リクエストは DownstreamConnection に入り、単一セッションロックを通じて下流のMCPにシリアルアクセス。

6. 呼び出し完了後、メトリクス、失敗回数、サーキットブレーカーを更新し、heartbeat / healthz に同期。

主要モジュールの役割は以下の通りです：

• shared_mcp_gateway/config.py：レジストリの解析と型安全な設定オブジェクト。

• shared_mcp_gateway/gateway.py：統合インデックス、リクエスト転送、サーキットブレーカー、ヘルスチェック、ハートビートログ。

• shared_mcp_gateway/stdio_bridge.py：stdioのみをサポートするクライアント向けにHTTPゲートウェイブリッジ層を提供。

• shared_mcp_gateway/render.py：統合レジストリを各クライアントの接続設定にレンダリング。

• scripts/self_check.py：ヘルスインターフェースと実際のMCP呼び出しの両面から接続性を自己診断。

リクエストシーケンス図

以下の図は、コードを読む際に全体像を把握するのに役立ちます：

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

コードリーディングのヒント

メインフローを素早く理解するには、以下の順序で読むことをお勧めします：

1. shared_mcp_gateway/config.py：レジストリ構造を理解する。

2. shared_mcp_gateway/render.py：クライアント接続設定がどのように生成されるかを理解する。

3. shared_mcp_gateway/stdio_bridge.py：stdioクライアントがどのようにHTTPゲートウェイに接続するかを理解する。

4. shared_mcp_gateway/gateway.py：SharedMcpGateway、DownstreamConnection、RequestLoggingMiddleware を重点的に確認する。

5. scripts/self_check.py：デプロイ後に「インターフェースが生きているか」と「実際の機能が利用可能か」を検証する方法を理解する。

クイックスタート

1. 依存関係のインストール

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

2. 設定の準備

テンプレートファイルを直接参考にしてください：

• templates/registry.template.toml

• templates/registry.compose.template.toml

• templates/docker-compose.template.yml

最も一般的な手順は以下の通りです：

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

その後、テンプレート内のパス、ポート、下流サービスのコマンドを実際の環境に合わせて書き換えてください。

3. ローカルでの直接起動

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

起動後、デフォルトで以下にアクセス可能です：

• MCPエンドポイント：http://127.0.0.1:8787/mcp

• ヘルスチェック：http://127.0.0.1:8787/healthz

4. Docker Compose での起動

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

停止：

docker compose down

設定方法：コア設定の説明

プロジェクトの主要な設定ファイルは registry.toml で、主に5つのセクションで構成されています：

1. リッスン設定

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

意味：

• host：ゲートウェイのリッスンアドレス

• port：ゲートウェイのリッスンポート

• path：MCP HTTPパス

2. ゲートウェイメタ情報

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

意味：

• name：外部に公開するゲートウェイ名

• namespace_separator：名前空間の区切り文字（デフォルトは .）

• description：ゲートウェイの説明情報

3. 下流MCPサーバー設定

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

意味：

• key：下流サービスのユニーク識別子

• enabled：有効化するかどうか

• namespace：ツール名のプレフィックス名前空間

• command：起動コマンド

• args：起動引数

• env：オプション、当該サービスに個別に注入する環境変数

4. ローカル例外の説明

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

共有ゲートウェイを通さず、ローカル直結を維持する機能を記録するために使用します。

5. クライアント設定パスのメタ情報（オプション）

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

意味：

• clients.* は主にターゲットクライアントの設定ファイルの場所を記録するために使用します。

• 本プロジェクトはデフォルトではこれらのパスに自動書き込みを行いません。

• scripts/render_client_configs.py を実行し、生成結果を各クライアントの設定にコピーすることを推奨します。

設定方法：事例

事例 1：ホストマシンでの直接実行設定

以下はそのまま参考にできる最小構成の例です：

[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 纳管。"

事例 2：Docker Compose での設定の考え方

コンテナ内でゲートウェイを一元的に実行したい場合は、以下の考え方を参考にしてください：

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

適したケース：

• 複数のMCPランタイム依存関係を同じコンテナコンテキストにマウントする場合。

• 読み取り専用マウントを通じて下流コードディレクトリの安定性を確保する場合。

• コンテナ内の registry.compose.toml を統一して使用する場合。

設定テンプレートファイル

導入を容易にするため、プロジェクトにはコピー可能なテンプレートファイルが用意されています：

1. レジストリテンプレート

ファイル：templates/registry.template.toml

用途：

• 新環境の初期化時にコピーしてパスを書き換える。

• ホストマシンでの直接実行の起点設定として適している。

• listen、gateway、servers、clients、local_exceptions の完全な構造を保持。

推奨される使用方法：

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

2. コンテナ内レジストリテンプレート

ファイル：templates/registry.compose.template.toml

用途：

• Docker / Compose シナリオ向けに、コンテナ内パスバージョンのレジストリテンプレートを提供。

• ホストマシンの絶対パスがコンテナ設定に混入するのを防ぐ。

• registry.compose.toml のコピー元として適している。

推奨される使用方法：

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

3. Compose テンプレート

ファイル：templates/docker-compose.template.yml

用途：

• 新しいマシンや環境でのComposeオーケストレーションの迅速な準備。

• 本番環境や現在のマシン専用の docker-compose.yml を直接修正するのを避ける。

• マウントパスや環境変数をチームの規約に合わせて変更しやすくする。

推奨される使用方法：

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

クライアント接続例

推奨される接続フロー：

1. まず shared-gateway を起動し、http://127.0.0.1:8787/healthz が正常であることを確認する。

2. python3 scripts/render_client_configs.py を実行し、現在の環境用のクライアント設定スニペットを生成する。

3. generated/ ディレクトリ内の実際の生成物を優先的にコピーし、環境依存のパスを手書きしない。

Codex 接続例

generated/codex-mcp.toml を直接使用することを推奨します。構造は概ね以下の通りです：

[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 接続例

generated/opencode-mcp.jsonc を直接使用することを推奨します。構造は概ね以下の通りです：

{
  "$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 接続例

OpenClaw は直接HTTP MCPを利用可能です。generated/openclaw-mcp.json の使用を推奨します：

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

Claude Code 接続の考え方

本プロジェクトは stdio_bridge.py を通じて claude-code に呼び出し元識別子を注入することをサポートしています。基本的な考え方は、ブリッジをローカルのstdio MCPコマンドとして使用することです：

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

クライアントの設定体系がカスタムstdio MCPコマンドを許可している場合、このブリッジコマンドをそのまま再利用できます。

設定導入のヒント

環境問題を減らすため、以下の順序で導入することをお勧めします：

1. テンプレートファイルをコピーし、プロジェクト内の既存サンプルを直接修正しない。

2. 各下流MCPサーバーが個別に起動できることを確認する。

3. 下流サービスを1つずつ registry.toml または registry.compose.toml に書き込む。

4. ゲートウェイ起動後、/healthz を確認し、scripts/self_check.py を実行する。

5. 最後に scripts/render_client_configs.py を実行し、クライアント接続設定を同期する。

以下の3種類のファイルを使い分けることを推奨します：

• registry.toml：ホストマシン直接実行用設定

• registry.compose.toml：コンテナ内実行用設定

• templates/*.template.*：新環境初期化用テンプレート

よく使うコマンド

クライアント設定の生成

python3 scripts/render_client_configs.py

このスクリプトは以下を行います：

• registry.toml を読み込む

• Codex / OpenCode / OpenClaw の設定スニペットを一括生成する

• ブリッジ起動コマンドを手動コピーする際の設定ドリフトを防ぐ

生成結果は以下に保存されます：

• generated/codex-mcp.toml

• generated/opencode-mcp.jsonc

• generated/openclaw-mcp.json

ヘルスチェックの実行

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

デフォルトで2種類のチェックを実行します：

• healthz：ゲートウェイが正常に公開されているか、下流が欠落していないか、サーキットブレーカーが開いていないかを確認。

• gateway_tools：MCPクライアントとしてゲートウェイに接続し、主要ツールが存在するかを確認し、副作用のない生存確認を実行。

ログの確認

docker compose logs -f shared-mcp-gateway

現在接続されている共有型MCP

• mempalace

• mysql-db

• obsidian-kb

• tencent-cls

トポロジーの詳細は /path/to/shared-mcp-gateway/docs/mcp-topology.md を参照してください。

今後の推奨事項

本プロジェクトをさらに拡張する場合は、以下の順序で進めることをお勧めします：

1. registry.toml に新しい [[servers]] を追加する。

2. そのMCPが単独で起動できるかをローカルで検証する。

3. ゲートウェイ起動後に /healthz を確認する。

4. scripts/self_check.py を実行し、主要機能が正常か確認する。

5. scripts/render_client_configs.py を再実行し、クライアント設定を同期する。

本プロジェクトでドキュメント、テンプレート、またはデフォルト設定を継続的にメンテナンスする場合は、以下を優先してください：

• README.md

• templates/registry.template.toml

• templates/registry.compose.template.toml

• templates/docker-compose.template.yml

• docs/mcp-topology.md