Shared MCP Gateway

여러 공유형 MCP 서버를 하나의 HTTP 게이트웨이로 통합하여, 외부로 안정적이고 관찰 가능하며 재사용 가능한 MCP 액세스 계층을 제공합니다. 이를 통해 Codex, OpenCode, Claude Code, OpenClaw 등 다양한 클라이언트가 공동으로 사용할 수 있도록 지원합니다.

프로젝트 해결 과제

다중 클라이언트 및 다중 MCP 서버를 병렬로 사용하는 환경에서는 일반적으로 다음과 같은 문제들이 발생합니다:

• 각 클라이언트마다 별도의 MCP 구성을 유지해야 하므로 중복 작업이 많음.

• 동일한 툴체인이 클라이언트마다 다르게 설정되어 '특정 클라이언트에서는 작동하지만 다른 곳에서는 안 되는' 현상이 발생하기 쉬움.

• 하위 MCP 서버에 이상이 생길 경우, 문제 해결을 위한 진입점이 분산되어 통합 로그, 자가 진단 및 서킷 브레이킹 처리가 불편함.

• 새로운 MCP 서버를 추가하거나 교체할 때마다 여러 개의 설정을 수정해야 하므로 변경 비용이 높음.

shared-mcp-gateway의 목표는 이러한 공유형 기능을 통합 관리하는 것입니다:

• 레지스트리 통합 관리: registry.toml / registry.compose.toml을 통해 하위 MCP를 통합 관리.

• 단일 액세스 포인트: 하나의 HTTP MCP 엔드포인트를 통해 여러 하위 서비스를 집계.

• 통합 운영 관리: 상태 확인, 구조화된 로그, 장애 격리, 최소 서킷 브레이킹을 통합 수행.

• 클라이언트 구성 자동 생성: Codex / OpenCode / OpenClaw용 액세스 구성 조각을 자동으로 생성.

Related MCP server: MCPHubs

프로젝트 기능

현재 프로젝트는 다음을 지원합니다:

• stdio 기반의 여러 하위 MCP 서버 집계.

• 하위 도구를 namespace.tool_name 방식으로 통합 노출.

• 클라이언트별로 caller 식별자를 자동으로 부여하여 로그 추적 용이.

• /healthz 상태 확인 인터페이스를 통해 연결된 서비스, 실패한 서비스, 서킷 브레이킹 상태 확인.

• grep, CLS, Loki 등 시스템에서 검색하기 쉬운 구조화된 logfmt 로그 제공.

• 하위 서비스 이상 발생 시 최소 격리를 수행하여 단일 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. 해당 하위 서비스가 서킷 브레이킹 상태라면, 요청을 즉시 거부하여 이상 서비스에 지속적인 부하가 걸리는 것을 방지.

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이며, 주로 다섯 부분으로 구성됩니다:

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. 하위 서비스를 하나씩 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의 구성 조각을 통합 생성

• 브리지 시작 명령을 수동으로 복사할 때 발생하는 구성 드리프트 방지

생성 결과 위치:

• generated/codex-mcp.toml

• generated/opencode-mcp.jsonc

• generated/openclaw-mcp.json

상태 확인 실행

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

기본적으로 두 가지 유형의 확인을 수행합니다:

• 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