IBM/mcp-context-forge · 上手攻略

是什么

mcp-context-forge(README 自称 ContextForge)是一个由 IBM 开源的 AI Gateway / Registry / Proxy:它把任意数量的 MCP(Model Context Protocol)服务器、A2A(Agent-to-Agent)服务器、REST/gRPC 后端统一汇聚到一个端点后面,对 AI 客户端(Claude Code、Cursor、自研 agent 等)暴露一致的"工具列表 + 工具调用"接口,同时提供集中的鉴权、限流、观测、插件扩展能力。换句话说,它做的是"AI 工具/Agent 的 API Gateway"——把分散的 MCP server 和 REST API 虚拟化成一台"虚拟 MCP server"。

它本身就是一个完全合规的 MCP server,所以任何 MCP 兼容客户端都可以直接对接它;后端则可以是任意 MCP server、任意 REST/gRPC 端点,甚至 OpenAI / Anthropic 兼容的远程 Agent。

解决什么问题

没有这个网关之前,一个生产级 agent 团队会撞到三面墙:

  1. 工具爆炸:每个团队成员各自挂载十几个 MCP server,客户端配置重复、命名冲突、schema 不一致,审计和鉴权也无从下手。
  2. 协议碎片:MCP 是 2025 主流,但很多老服务只暴露 REST/gRPC;agent 想用它们,得手写 JSON Schema + 鉴权 + 重试。
  3. 观测与治理盲区:LLM 调用链路散落在 N 个 server,token 成本、失败率、p99 延迟没法统一打点;权限模型要么太松要么太死。

ContextForge 把"工具/Agent/API"都抽象成同一类注册资源,客户端只需对接一个 gateway,网关负责:

  • 自动 REST/gRPC → MCP 适配(含 gRPC 反射自发现、JSON Schema 抽取、TOON 压缩)
  • 联邦多 MCP/A2A server(支持 HTTP / JSON-RPC / WebSocket / SSE / stdio / streamable-HTTP)
  • OAuth、JWT、Basic、用户级 token、Vault 凭据解析、SSRF/TLS 校验
  • OpenTelemetry trace + metrics,可接 Phoenix / Jaeger / Zipkin / Tempo / DataDog / New Relic
  • 插件层(40+ 插件)+ Admin UI(HTMX 2.0.3 + Alpine.js)

快速安装

官方推荐 Python ≥ 3.11;首次启动前必须生成 JWT_SECRET_KEY 和 AUTH_ENCRYPTION_SECRET,否则 gateway 直接拒绝启动。

最小可跑命令(uv / PyPI)

# 0) 准备:Python 3.11+ + uv(可选)
# 1) 拉取并初始化 .env
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env
python3 -m mcpgateway.scripts.init_secrets        # 写 .env.secrets
python3 -m mcpgateway.scripts.init_secrets --patch-env .env   # 替换 __REPLACE_ME__

# 2) 启动 gateway(后台运行)
mcpgateway --host 0.0.0.0 --port 4444 &

# 3) 生成 bearer token 并冒烟测试
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  http://127.0.0.1:4444/version | jq

Docker 一行启动也可:

docker run -d --name mcpgateway -p 4444:4444 \
  -e JWT_SECRET_KEY="$(openssl rand -hex 32)" \
  -e AUTH_ENCRYPTION_SECRET="$(openssl rand -hex 32)" \
  -e MCPGATEWAY_UI_ENABLED=true \
  -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  ghcr.io/ibm/mcp-context-forge:latest

硬件 / 依赖:Python 3.11+、SQLite(默认)/ PostgreSQL(生产)、可选 Redis 做多集群缓存与联邦。不需要 GPU,纯网络 + 数据库负载。

核心用法

1) 注册一个外部 MCP server / REST API 作为"虚拟 MCP server"

# 注册一个 stdio MCP server(如 mcp-server-git)
python3 -m mcpgateway.translate \
  --stdio "uvx mcp-server-git" \
  --expose-sse --expose-streamable-http --port 9000

# 把刚启动的 SSE 端点登记到 gateway
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"git","url":"http://localhost:9000/sse"}' \
  http://localhost:4444/gateways

# 看一下工具清单
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  http://localhost:4444/tools | jq

2) 把若干工具打包成"虚拟 server"

# 从工具清单里挑出要暴露的工具 ID,组成虚拟 server
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"server":{"name":"time_server","description":"Fast time tools",
        "associated_tools":["6018ca46d32a4ac6b4c054c13a1726a2"]}}' \
  http://localhost:4444/servers | jq

之后,任何 MCP 客户端(Claude Code、Cursor、MCP Inspector 等)只需对接:

http://localhost:4444/servers/<UUID>/mcp

Header: Authorization: Bearer <token>。

3) A2A Agent 路由

Gateway 同时支持 OpenAI / Anthropic 兼容的远程 Agent 注册与调用,/a2a 路径下可直接转发,适合"agent 调用 agent"的多层编排。

4) 观测与限流

  • 启用 OpenTelemetry 后,在 mcpgateway translate 注入的 trace context 会贯穿到下游 MCP server,可在 Phoenix UI 直接看 LLM 调用成本、token 用量、错误率。
  • 限流、鉴权、重试、SSRF/TLS 校验默认开启,1.0.6 起 header key 校验更严格(空白字符会被 trim,非法 key 在配置时直接 422)。

典型适用场景

  • 企业内部 AI 工具目录:HR、IT、数据团队各自维护 MCP server,统一在 gateway 注册,对外只暴露一个端点。
  • Agent 编排中台:把若干外部 agent(OpenAI/Anthropic/自研)用 A2A 注册到网关,网关做调度、限流、token 计费。
  • REST 老系统接入 LLM:不想写完整 MCP server 的老 REST 服务,通过 mcpgateway.translate + REST-to-MCP 适配器,几分钟变 MCP 工具。
  • 多集群 / 多 region 部署:Redis 联邦缓存,K8s 上水平扩展,Admin UI 支持 air-gapped 部署,适合金融/政企内网。
  • 审计与合规:统一鉴权、用户级 token、Vault 凭据解析、SSRF/TLS 校验,所有调用落 OpenTelemetry,便于做合规审计。

坑与注意

  1. 首次启动必生成两个 secret:不跑 init_secrets 就启动,会直接退出。生产部署一定要把这两个值放进 Vault / k8s Secret。
  2. NPM 安装方式已废弃(README 顶部明确标注);MCP 客户端侧要的是 gateway URL + bearer token,不要直接 pip install mcp 然后用 stdio 拉它,要走 HTTP/SSE/streamable-HTTP。
  3. 配置变更 header key 校验收紧:1.0.6 起,X Api Key 这种带空格的 header key 直接 422;老的 gateway 配置升级前要先批量修正。
  4. Admin UI 启用需显式开关:MCPGATEWAY_UI_ENABLED=true 与 MCPGATEWAY_ADMIN_API_ENABLED=true 默认未必开,远程管理要主动设。
  5. SQLite 仅适合单实例 / 开发:生产建议 PostgreSQL + Redis,联邦与缓存才能水平扩展。
  6. README 自身有断章:750KB 抓取截断,部分示例(如 init_secrets --patch-env)是从 PyPI 文档拼出来的,命令路径以仓库 main 分支为准,本文不另行冒烟——若你跑起来报错,以 [issue 2503 5-Minute Setup](https://github.com/IBM/mcp-context-forge/issues/2503) 为准。
  7. 基准数字缺失:README 没给"每秒工具调用多少""p99 延迟""并发上限",这是 LLM 平台常见的"功能罗列 / 缺 benchmark"病,本文不杜撰。

与同类对比

项目 定位 协议覆盖 鉴权/观测 License
IBM/mcp-context-forge 企业级 AI Gateway + Registry MCP / A2A / REST / gRPC OAuth/JWT/Vault + OTel(Phoenix/Jaeger) Apache 2.0
Portkey Gateway LLM API Gateway(多模型路由) OpenAI/Anthropic 兼容 Key 鉴权 + 日志 Apache 2.0
LiteLLM Proxy LLM 统一接口层 多 provider 简单鉴权 + 日志 MIT
MCP Router / MCPHub 等社区项目 轻量 MCP 联邦 MCP 为主 视项目而异 多为 MIT

差异化:ContextForge 不是 LLM 路由代理(那是 LiteLLM / Portkey 的活),它聚焦"工具/Agent 的联邦与治理",且把 gRPC-to-MCP、TOON 压缩、SSRF/TLS 校验这些企业级能力作为一等公民——同等量级的开源项目目前少有能打的。

一句话推荐结论

"AI 工具/Agent 的 API Gateway"——如果你的 agent 要调用 ≥3 个 MCP server 或需要把 REST/gRPC 老服务接入 LLM,ContextForge 是当下 Apache 2.0 阵营里功能最全的可选项;若只是要"统一调多家 LLM",用 LiteLLM / Portkey 更轻。

源链接 / 引用