MCP Gateway实战：多服务器统一网关与路由编排

graph TB
    CC["Claude Code<br/>单一连接点"]

    subgraph GW["MCP Gateway"]
        R["路由引擎<br/>JSON-RPC分发"]
        A["认证层<br/>API Key / OAuth"]
        L["限流层<br/>Rate Limiting"]
        H["健康检查<br/>Heartbeat"]
        T["工具聚合<br/>Tool Aggregation"]
    end

    S1["GitHub<br/>MCP Server"]
    S2["PostgreSQL<br/>MCP Server"]
    S3["Slack<br/>MCP Server"]
    S4["Filesystem<br/>MCP Server"]
    S5["Jira<br/>MCP Server"]

    CC -->|SSE/HTTP| R
    R --> A --> L --> T
    T --> S1
    T --> S2
    T --> S3
    T --> S4
    T --> S5
    H -.->|监控| S1
    H -.->|监控| S2
    H -.->|监控| S3
    H -.->|监控| S4
    H -.->|监控| S5

    style GW fill:#1a1a2e,color:#fff
    style CC fill:#16213e,color:#fff

sequenceDiagram
    participant CC as Claude Code
    participant GW as MCP Gateway
    participant GH as GitHub Server
    participant DB as Database Server

    CC->>GW: initialize (JSON-RPC)
    GW->>GH: initialize
    GW->>DB: initialize
    GH-->>GW: tools: [repo_list, issue_create, ...]
    DB-->>DB: tools: [query, migrate, ...]
    GW-->>CC: 聚合工具列表

    CC->>GW: tools/call {name: "repo_list", ...}
    GW->>GW: 查路由表 → GitHub Server
    GW->>GH: tools/call {name: "repo_list", ...}
    GH-->>GW: 返回仓库列表
    GW-->>CC: 透传结果

    CC->>GW: tools/call {name: "query", ...}
    GW->>GW: 查路由表 → Database Server
    GW->>DB: tools/call {name: "query", ...}
    DB-->>GW: 返回查询结果
    GW-->>CC: 透传结果

# 安装Docker MCP Gateway CLI插件
docker extension install docker/mcp-gateway

# 验证安装
docker mcp version

# catalog.yaml
version: "1.0"

mcpServers:
  # GitHub MCP Server - stdio传输
  github:
    image: ghcr.io/github/github-mcp-server:latest
    transport: stdio
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    tools:
      - repo_list
      - issue_create
      - pr_review

  # PostgreSQL MCP Server - stdio传输
  postgres:
    image: mcp/postgres:latest
    transport: stdio
    env:
      POSTGRES_CONNECTION_STRING: "${DB_URI}"
    tools:
      - query
      - list_tables
      - describe_table

  # Slack MCP Server - 远程HTTP传输
  slack:
    url: https://slack-mcp.internal.company.com/sse
    transport: sse
    headers:
      Authorization: "Bearer ${SLACK_TOKEN}"
    tools:
      - send_message
      - list_channels
      - search_messages

# 启动Gateway（会自动拉取镜像、启动容器、注册工具）
docker mcp gateway start --catalog catalog.yaml

# Gateway默认监听 http://localhost:8811/sse
# 查看注册的工具
docker mcp tools list

# 注册为HTTP类型MCP Server
claude mcp add-http my-gateway \
  http://localhost:8811/sse \
  --header "Authorization: Bearer ${GATEWAY_TOKEN}"

# 验证连接
claude mcp list

● my-gateway (HTTP)
  Status: connected
  Tools: repo_list, issue_create, pr_review, query, list_tables, 
         describe_table, send_message, list_channels, search_messages

# 检查8811端口
lsof -i :8811

# 使用自定义端口启动
docker mcp gateway start --catalog catalog.yaml --port 9900

mcpServers:
  slack:
    url: https://slack-mcp.internal.company.com/sse
    transport: sse
    timeout: 60s

graph LR
    subgraph "Control Plane"
        CP["MCP Gateway<br/>Controller"]
        CR["MCPRoute CRD"]
    end

    subgraph "Data Plane"
        DP1["Gateway Pod 1"]
        DP2["Gateway Pod 2"]
    end

    subgraph "Backend Servers"
        B1["GitHub MCP<br/>Deployment"]
        B2["Postgres MCP<br/>Deployment"]
        B3["Slack MCP<br/>Deployment"]
    end

    CP -->|下发路由配置| DP1
    CP -->|下发路由配置| DP2
    CR -->|声明式配置| CP

    DP1 --> B1
    DP1 --> B2
    DP2 --> B1
    DP2 --> B3

    style CP fill:#0078d4,color:#fff
    style CR fill:#0078d4,color:#fff

# 添加Helm仓库
helm repo add mcp-gateway https://microsoft.github.io/mcp-gateway
helm repo update

# 安装Gateway
helm install mcp-gateway mcp-gateway/mcp-gateway \
  --namespace mcp-system \
  --create-namespace \
  --set gateway.replicas=2 \
  --set gateway.service.type=ClusterIP

# mcproute.yaml
apiVersion: mcp.microsoft.com/v1alpha1
kind: MCPRoute
metadata:
  name: dev-tools-route
  namespace: mcp-system
spec:
  routes:
    - name: github
      backend:
        service: github-mcp
        port: 3000
      sessionAffinity: true

    - name: postgres
      backend:
        service: postgres-mcp
        port: 3000
      sessionAffinity: true

    - name: slack
      backend:
        service: slack-mcp
        port: 3000
      sessionAffinity: true

# 应用路由配置
kubectl apply -f mcproute.yaml

# 检查Gateway状态
kubectl get mcproute -n mcp-system
kubectl logs -n mcp-system -l app=mcp-gateway

# 通过Ingress暴露
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mcp-gateway
  namespace: mcp-system
spec:
  rules:
    - host: mcp.company.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: mcp-gateway
                port:
                  number: 8080
EOF

# 在Claude Code中注册
claude mcp add-http k8s-gateway \
  https://mcp.company.com/sse \
  --header "Authorization: Bearer ${K8S_GATEWAY_TOKEN}" \
  --scope user

# 克隆仓库
git clone https://github.com/globalpocket/mcp-routing-gateway.git
cd mcp-routing-gateway

# 安装依赖
npm install

# 编辑路由配置
cat > config/routes.json <<'EOF'
{
  "routes": [
    {
      "name": "github",
      "match": "^github_",
      "backend": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    },
    {
      "name": "filesystem",
      "match": "^fs_",
      "backend": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      }
    },
    {
      "name": "postgres",
      "match": "^pg_",
      "backend": {
        "type": "sse",
        "url": "http://localhost:5433/sse"
      }
    }
  ],
  "default": {
    "type": "error",
    "message": "No matching route for tool"
  }
}
EOF

# 启动（默认监听 localhost:3000）
npm start -- --config config/routes.json --port 3000

# 或者使用环境变量
GITHUB_TOKEN=ghp_xxx npm start

# SSE模式
claude mcp add-http routing-gw http://localhost:3000/sse --scope project

# 或者用stdio模式（Gateway本身也支持stdio）
claude mcp add routing-gw -- node /path/to/mcp-routing-gateway/index.js --config config/routes.json

{
  "mcpServers": {
    "my-gateway": {
      "type": "http",
      "url": "http://localhost:8811/sse",
      "enable_tool_search": true
    }
  }
}

claude mcp add-http my-gateway http://localhost:8811/sse \
  --enable-tool-search

graph TD
    A["Claude Code启动"] --> B{"工具描述 > 10% 上下文?"}
    B -->|"否"| C["全量加载（默认行为）"]
    B -->|"是"| D["启用Tool Search<br/>仅加载tool_search元工具"]

    D --> E["Claude收到用户请求"]
    E --> F["Claude调用 tool_search<br/>query='查询数据库中的用户表'"]
    F --> G["Gateway返回匹配工具:<br/>pg_query, pg_list_tables"]
    G --> H["Claude按需加载工具描述"]
    H --> I["Claude调用目标工具"]

    style D fill:#e94560,color:#fff
    style F fill:#0f3460,color:#fff

// 在MCP Server的工具定义中
server.tool("pg_query_users", 
  "Query users table in PostgreSQL database. Tags: [database, postgres, users, query]",
  { sql: z.string().describe("SQL query to execute") },
  async ({ sql }) => { /* ... */ }
);

mcp-gateway/
├── docker-compose.yml
├── catalog.yaml
├── .env.example
├── nginx/
│   └── nginx.conf        # 反向代理+TLS终止
└── prometheus/
    └── mcp-rules.yml      # 监控告警规则

version: "3.8"

services:
  # MCP Gateway
  mcp-gateway:
    image: docker/mcp-gateway:latest
    ports:
      - "8811:8811"
    volumes:
      - ./catalog.yaml:/app/catalog.yaml:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - GATEWAY_PORT=8811
      - LOG_LEVEL=info
      - AUTH_TOKEN=${GATEWAY_TOKEN}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8811/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

  # GitHub MCP Server（容器化）
  github-mcp:
    image: ghcr.io/github/github-mcp-server:latest
    environment:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN}
    restart: unless-stopped

  # PostgreSQL MCP Server
  postgres-mcp:
    image: mcp/postgres:latest
    environment:
      POSTGRES_CONNECTION_STRING: ${DB_URI}
    restart: unless-stopped

  # Nginx反向代理（TLS终止）
  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/certs:/etc/nginx/certs:ro
    depends_on:
      - mcp-gateway
    restart: unless-stopped

  # Prometheus监控
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus:/etc/prometheus:ro
      - prometheus-data:/prometheus
    restart: unless-stopped

volumes:
  prometheus-data:

version: "1.0"

mcpServers:
  github:
    image: ghcr.io/github/github-mcp-server:latest
    transport: stdio
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

  postgres:
    image: mcp/postgres:latest
    transport: stdio
    env:
      POSTGRES_CONNECTION_STRING: "${DB_URI}"

  filesystem:
    image: mcp/filesystem:latest
    transport: stdio
    args:
      - "/shared/projects"

  brave-search:
    image: mcp/brave-search:latest
    transport: stdio
    env:
      BRAVE_API_KEY: "${BRAVE_API_KEY}"

# 复制为 .env 并填入真实值
GATEWAY_TOKEN=your-gateway-auth-token-here
GITHUB_TOKEN=ghp_your_github_pat
DB_URI=postgresql://user:pass@db-host:5432/mydb
BRAVE_API_KEY=BSA_your_brave_key

# 设置Gateway地址（团队共用）
export MCP_GATEWAY_URL=https://mcp.internal.company.com/sse
export MCP_GATEWAY_TOKEN=your-team-gateway-token

# 注册到Claude Code（user scope，所有项目可用）
claude mcp add-http team-gateway \
  $MCP_GATEWAY_URL \
  --header "Authorization: Bearer $MCP_GATEWAY_TOKEN" \
  --enable-tool-search \
  --scope user

# 验证
claude mcp list

graph TD
    subgraph "团队成员 A"
        CC1["Claude Code"]
    end

    subgraph "团队成员 B"
        CC2["Claude Code"]
    end

    subgraph "团队成员 C"
        CC3["Claude Code"]
    end

    subgraph "共享基础设施"
        NGINX["Nginx<br/>TLS终止"]
        GW["Docker MCP Gateway<br/>:8811"]
        PROM["Prometheus<br/>:9090"]

        GH["GitHub MCP"]
        PG["Postgres MCP"]
        FS["Filesystem MCP"]
        BS["Brave Search MCP"]
    end

    CC1 -->|HTTPS| NGINX
    CC2 -->|HTTPS| NGINX
    CC3 -->|HTTPS| NGINX
    NGINX -->|HTTP| GW

    GW --> GH
    GW --> PG
    GW --> FS
    GW --> BS

    GW -.->|metrics| PROM

    style NGINX fill:#009639,color:#fff
    style GW fill:#1a1a2e,color:#fff
    style PROM fill:#e6522c,color:#fff

# 查看Gateway日志
docker mcp gateway logs

# 常见原因：后端Server崩溃
# 检查各后端容器状态
docker ps --filter "name=mcp"

# 重启单个后端
docker restart mcp-gateway-github-mcp-1

# 重启整个Gateway
docker mcp gateway restart

# 检查Gateway是否成功连接后端
docker mcp tools list --verbose

# 如果后端需要环境变量但未传入
# 检查.env文件
cat .env | grep -v '^#' | grep -v '^$'

# 重新加载catalog
docker mcp gateway reload --catalog catalog.yaml

# 查看Gateway超时配置
docker mcp gateway config show | grep timeout

# 在catalog.yaml中增加超时
# 某些数据库查询可能需要更长时间
mcpServers:
  postgres:
    timeout: 120s  # 从默认30s增加到120s

# 验证Gateway Token
curl -H "Authorization: Bearer $MCP_GATEWAY_TOKEN" \
  http://localhost:8811/health

# 检查Claude Code配置
claude mcp get team-gateway
# 确认header中的token与Gateway端配置一致

# 检查哪些Server支持Tool Search
claude mcp list --verbose
# 输出中会显示每个Server的tool search状态

# Docker MCP Gateway
docker mcp gateway start --catalog catalog.yaml --log-level debug

# mcp-routing-gateway
DEBUG=mcp:* npm start -- --config config/routes.json

graph LR
    START["选择Gateway方案"] --> Q1{"部署环境?"}

    Q1 -->|"单机/开发"| Q2{"需要容器化?"}
    Q1 -->|"Kubernetes"| MS["Microsoft MCP<br/>Gateway"]
    Q1 -->|"需要API网关能力"| EN["Envoy AI Gateway"]

    Q2 -->|"是"| DK["Docker MCP<br/>Gateway"]
    Q2 -->|"否"| Q3{"工具数量?"}

    Q3 -->|"< 20"| MR["mcp-routing-<br/>gateway"]
    Q3 -->|"> 20"| DK

    style START fill:#533483,color:#fff
    style MS fill:#0078d4,color:#fff
    style EN fill:#e6522c,color:#fff
    style DK fill:#2496ed,color:#fff
    style MR fill:#339af0,color:#fff

Claude Code
    ↓
Envoy AI Gateway（API管理、限流、TLS终止）
    ↓
Docker MCP Gateway（工具聚合、路由）
    ↓
各个MCP Server

# 区域Gateway配置（us-west-2）
mcpServers:
  local-postgres:
    url: http://postgres-mcp.us-west-2.internal:3000/sse
  local-filesystem:
    url: http://fs-mcp.us-west-2.internal:3000/sse

  # 通过联邦访问其他区域的工具
  eu-github:
    type: federated
    gateway: https://mcp-gateway.eu-central-1.company.com/sse
    route: github

# Gateway地址 → user scope（所有项目共用一个Gateway）
claude mcp add-http team-gateway https://mcp.company.com/sse \
  --scope user --enable-tool-search

# 项目特定Server → project scope（提交到Git）
# .mcp.json
{
  "mcpServers": {
    "local-storybook": {
      "type": "http",
      "url": "http://localhost:6006/sse"
    }
  }
}

# 正确做法
mcpServers:
  github:
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"  # 从.env读取

# 错误做法
mcpServers:
  github:
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_abc123def456"  # 绝对禁止

{
  "mcpServers": {
    "team-gateway": {
      "type": "http",
      "url": "https://mcp.company.com/sse",
      "headers": {
        "Authorization": "Bearer ${GATEWAY_TOKEN}"
      }
    }
  }
}

echo ".env" >> .gitignore

# Docker MCP Gateway支持优雅关闭
docker mcp gateway stop --grace-period 30s

# Kubernetes环境中，设置terminationGracePeriodSeconds
# 在Deployment中：
spec:
  terminationGracePeriodSeconds: 60

graph TD
    P1["Phase 1: 评估<br/>清点当前MCP Server数量<br/>测量上下文占用"]
    --> P2["Phase 2: 选型<br/>根据团队规模和基础设施<br/>选择Gateway方案"]

    P2 --> P3["Phase 3: 开发环境<br/>部署Gateway<br/>迁移1-2个Server验证"]

    P3 --> P4["Phase 4: 全量迁移<br/>所有Server迁移到Gateway<br/>启用Tool Search"]

    P4 --> P5["Phase 5: 生产加固<br/>添加认证/限流/监控<br/>编写运维手册"]

    P5 --> P6["Phase 6: 持续优化<br/>根据监控数据调优<br/>评估多区域部署"]

    style P1 fill:#2d3436,color:#fff
    style P3 fill:#00b894,color:#fff
    style P5 fill:#e17055,color:#fff

# 查看当前所有MCP Server
claude mcp list

# 统计工具总数
claude mcp list --json | jq '[.[].tools | length] | add'
# 如果输出 > 30，强烈建议引入Gateway