Shared MCP Gateway

Унифицирует несколько общих MCP-серверов в единый HTTP-шлюз, предоставляя стабильный, наблюдаемый и повторно используемый уровень доступа MCP для совместного использования такими клиентами, как Codex, OpenCode, Claude Code, OpenClaw и другими.

Какие проблемы решает проект

В сценариях с использованием нескольких клиентов и нескольких MCP-серверов параллельно часто возникают следующие проблемы:

• Каждый клиент требует отдельного обслуживания конфигурации MCP, что ведет к дублированию работы.

• Конфигурация одного и того же набора инструментов в разных клиентах различается, что приводит к ситуациям, когда «в этом клиенте работает, а в том — нет».

• При возникновении проблем с нижестоящим MCP-сервером точки отладки разбросаны, что затрудняет централизованное логирование, самодиагностику и обработку сбоев.

• При добавлении или замене MCP-сервера необходимо вносить изменения в несколько конфигураций, что увеличивает затраты на сопровождение.

Цель shared-mcp-gateway — централизованное управление этими общими возможностями:

• Единый реестр: централизованное управление нижестоящими MCP через registry.toml / registry.compose.toml.

• Единая точка доступа: агрегация нескольких нижестоящих сервисов через одну HTTP MCP-конечную точку.

• Единое управление эксплуатацией: унифицированные проверки работоспособности, структурированные логи, изоляция сбоев и минимальное отключение (circuit breaking).

• Единая генерация конфигураций клиентов: автоматическое создание фрагментов конфигурации доступа для Codex / OpenCode / OpenClaw.

Related MCP server: mcp-uni

Возможности проекта

Текущая версия поддерживает:

• Агрегацию нескольких нижестоящих MCP-серверов на базе stdio.

• Унифицированное предоставление инструментов в формате 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 требовалось изменить только один файл реестра.

Структура проекта

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. Если соответствующий сервис отключен (circuit breaker), запрос быстро отклоняется, чтобы избежать нагрузки на неисправный сервис.

5. Если пересылка разрешена, запрос поступает в DownstreamConnection, где доступ к нижестоящему MCP осуществляется последовательно через блокировку сессии.

6. После завершения вызова обновляются метрики, счетчик сбоев, состояние circuit breaker, и данные синхронизируются с heartbeat / healthz.

Рекомендуемое понимание обязанностей основных модулей:

• shared_mcp_gateway/config.py: парсинг реестра и строго типизированные объекты конфигурации.

• shared_mcp_gateway/gateway.py: унифицированная индексация, пересылка запросов, изоляция сбоев, проверки работоспособности, логи heartbeat.

• shared_mcp_gateway/stdio_bridge.py: мост HTTP-шлюза для клиентов, поддерживающих только stdio.

• 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, который содержит пять основных частей:

1. Конфигурация прослушивания

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

Значение:

• host: адрес прослушивания шлюза

• port: порт прослушивания шлюза

• path: HTTP-путь MCP

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

Текущий проект уже поддерживает внедрение идентификатора вызывающей стороны для claude-code через stdio_bridge.py. Основная идея заключается в использовании bridge в качестве локальной команды 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, просто повторно используйте эту команду bridge.

Рекомендации по внедрению конфигурации

Чтобы уменьшить количество проблем со средой, рекомендуется внедрять в следующем порядке:

1. Сначала скопируйте файлы шаблонов, не изменяйте готовые примеры внутри проекта напрямую.

2. Сначала убедитесь, что каждый нижестоящий MCP-сервер может быть запущен отдельно.

3. Затем по очереди вносите нижестоящие сервисы в registry.toml или registry.compose.toml.

4. После запуска шлюза сначала проверьте /healthz, затем выполните scripts/self_check.py.

5. Наконец, выполните scripts/render_client_configs.py для синхронизации конфигурации доступа клиентов.

Рекомендуется различать три типа файлов:

• registry.toml: конфигурация для прямого запуска на хосте

• registry.compose.toml: конфигурация для запуска внутри контейнера

• templates/*.template.*: шаблоны для инициализации новой среды

Часто используемые команды

Генерация конфигурации клиента

python3 scripts/render_client_configs.py

Этот скрипт:

• Читает registry.toml

• Унифицированно генерирует фрагменты конфигурации для Codex / OpenCode / OpenClaw

• Позволяет избежать дрейфа конфигурации при ручном копировании команд запуска bridge

Результаты генерации находятся в:

• generated/codex-mcp.toml

• generated/opencode-mcp.jsonc

• generated/openclaw-mcp.json

Выполнение проверки работоспособности

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

По умолчанию выполняются два типа проверок:

• healthz: проверка того, что шлюз работает нормально, нижестоящие сервисы на месте, а выключатель (circuit breaker) не сработал.

• 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. Сначала добавьте новый [[servers]] в registry.toml.

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