ghcr.io/ibm/mcp-context-forge:765f50d2f5151b5e8d810b9bf0bd682ca46d4185

ContextForge

这是一款开源注册中心与代理服务，可对 MCP、A2A 以及 REST/gRPC API 执行联邦聚合，提供集中治理、服务发现与可观测性能力。它可优化智能体与工具调用流程，同时支持插件扩展。

ContextForge 是一款开源注册中心与代理服务，可将各类工具、智能体与 API 联邦聚合为一个统一的干净端点，供你的 AI 客户端使用。它在整个 AI 基础设施范围内提供集中治理、服务发现与可观测性能力：

• 工具网关 — 支持 MCP、REST、gRPC 到 MCP 的转换，以及 TOON 压缩
• 智能体网关 — 支持 A2A 协议、兼容 OpenAI 与 Anthropic 的智能体路由
• API 网关 — 为 REST 服务提供限流、认证、重试与反向代理能力
• 插件扩展 — 提供 40 余款插件，用于支持更多传输方式、协议与集成场景
• 可观测性 — 基于 OpenTelemetry 实现链路追踪，兼容 Phoenix、Jaeger、Zipkin 等各类 OTLP 后端

它作为完全符合规范的 MCP 服务运行，可通过 PyPI 或 Docker 部署，并能依托 Redis 实现联邦与缓存，在 Kubernetes 上扩展至多集群环境。

---

目录

• 概述与目标
• 快速入门 - PyPI 部署
• 快速入门 - 容器部署
• VS Code 开发容器
• 安装
• 升级
• 配置
• 运行
• 云部署
• API 参考
• 测试
• 项目结构
• 开发指南
• 故障排查
• 贡献指南

---

📌 快速链接

---

概述与目标

ContextForge 是一款开源注册中心与代理服务，可对任意 https://modelcontextprotocol.io（MCP）服务、A2A 服务或 REST/gRPC API 执行联邦聚合，提供集中治理、服务发现与可观测性能力。它可优化智能体与工具调用流程，同时支持插件扩展。更多详情请查看https://ibm.github.io/mcp-context-forge/architecture/roadmap/。

当前支持以下功能：

• 跨多个 MCP 与 REST 服务的联邦聚合
• A2A（智能体间）集成，支持对接外部 AI 智能体（OpenAI、Anthropic、自定义智能体）
• gRPC 转 MCP 转换，基于自动反射实现服务发现
• 将存量 API 虚拟化改造为符合 MCP 规范的工具与服务
• 支持 HTTP、JSON-RPC、WebSocket、SSE（可配置 keepalive）与 Streamable HTTP 传输；同时提供 stdio 传输供服务端场景使用
• 配套管理 UI，支持实时管理、配置与日志监控（支持离线隔离部署场景）
• 内置认证、重试与限流能力，支持用户范围的 OAuth 令牌与无条件 X-Upstream-Authorization 头传递
• OpenTelemetry 可观测性，兼容 Phoenix、Jaeger、Zipkin 等各类 OTLP 后端
• 支持通过 Docker 或 PyPI 实现弹性扩展部署，配备基于 Redis 的缓存与多集群联邦能力

如需查看即将推出的功能列表，请访问 https://ibm.github.io/mcp-context-forge/architecture/roadmap/。

---

🔌 灵活协议网关层

• 可聚合任意 MCP 服务或 REST API
• 支持自主选择 MCP 协议版本（例如 2025-11-25）
• 为各类异构后端暴露统一接口

🧩 REST/gRPC 服务虚拟化

• 将非 MCP 服务封装为虚拟 MCP 服务
• 仅需极少配置即可注册工具、提示词与资源
• 通过服务器反射协议实现 gRPC 转 MCP 转换
• 自动服务发现与方法内省

🔁 REST 转 MCP 工具适配器

• 将 REST API 适配为工具，支持以下能力：
• 自动提取 JSON Schema
• 支持自定义请求头、令牌与认证配置
• 可配置重试、超时与限流策略

🧠 统一注册中心

• 提示词：支持 Jinja2 模板、多模态、回滚与版本管理
• 资源：基于 URI 访问、MIME 类型检测、缓存、SSE 更新
• 工具：原生工具或适配生成工具，自带输入校验与并发控制

📈 管理 UI、可观测性与开发体验

• 基于 HTMX 2.0.3（内置打包）+ Alpine.js 构建的管理 UI
• 实时日志查看器，支持过滤、搜索与导出
• 认证方式：Basic、JWT 或自定义方案
• 结构化日志、健康检查端点、指标采集
• 7000+ 测试用例、Makefile 目标、热重载、pre-commit 钩子

🔍 OpenTelemetry 可观测性

• 厂商无关的链路追踪，支持 OpenTelemetry（OTLP）协议
• 多后端兼容：Phoenix（面向大语言模型场景）、Jaeger、Zipkin、Tempo、DataDog、New Relic
• 跨联邦网关与服务的分布式追踪
• 对工具、提示词、资源与网关操作实现自动埋点
• 面向大语言模型场景的专属指标：令牌用量、成本、模型性能
• 禁用时零额外开销，优雅降级

如需查看针对 Phoenix、Jaeger 等后端的配置指南，请参阅 **https://ibm.github.io/mcp-context-forge/manage/observability/**。

---

快速入门 - PyPI 部署

ContextForge 已作为 mcp-contextforge-gateway 发布在 https://pypi.org/project/mcp-contextforge-gateway/ 平台。

---

[!WARNING] 所有环境（包括本地开发环境）都必须配置 JWT_SECRET_KEY 与 AUTH_ENCRYPTION_SECRET，缺少任意一项网关都无法启动。请在首次运行前执行 python3 -m mcpgateway.scripts.init_secrets 生成正式的密钥。

精简指南 — 使用 uv 只需一条命令即可完成启动：

# 1️⃣ 生成安全密钥（自动创建 .env.secrets 文件）
python3 -m mcpgateway.scripts.init_secrets

# 2️⃣ 导出生成的密钥值
export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"

# 3️⃣ 启动网关
JWT_SECRET_KEY="$JWT_SECRET_KEY" \
AUTH_ENCRYPTION_SECRET="$AUTH_ENCRYPTION_SECRET" \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

📋 前置依赖

• Python ≥ 3.11
• curl + jq — 仅最后冒烟测试步骤需要

1 - 安装与运行（可直接复制粘贴执行）

# 1️⃣ 创建隔离环境并从 PyPI 安装
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣ 下载 .env.example 并生成真实密钥
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env

# 将密码学安全密钥生成到 .env.secrets 文件中
python3 -m mcpgateway.scripts.init_secrets

# 将生成的密钥补入 .env 文件（替换其中的 __REPLACE_ME__ 占位符）
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣ 启动网关
mcpgateway --host 0.0.0.0 --port 4444 &

# 4️⃣ 生成 Bearer 令牌并执行冒烟测试
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

Windows (PowerShell) 快速入门

# 1️⃣ 创建隔离环境 + 从 PyPI 安装
mkdir mcpgateway ; cd mcpgateway
python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣ 下载 .env.example 并生成真实密钥
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env

# 将密码学安全密钥生成到 .env.secrets 文件中
python3 -m mcpgateway.scripts.init_secrets

# 将生成的密钥补入 .env 文件（替换其中的 __REPLACE_ME__ 占位符）
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣ 启动网关
mcpgateway.exe --host 0.0.0.0 --port 4444

# 4️⃣ 生成 Bearer 令牌并执行冒烟测试
$Env:JWT_SECRET_KEY = (Get-Content .env | Select-String '^JWT_SECRET_KEY=').ToString().Split('=')[1]
$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
--username admin@example.com --exp 10080 --secret $Env:JWT_SECRET_KEY

curl -s -H "Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN" `
http://127.0.0.1:4444/version | jq

⚡ 替代方案：使用 uv（速度更快）

# 1️⃣ 使用 uv 创建隔离环境 + 从 PyPI 安装
mkdir mcpgateway ; cd mcpgateway
uv venv
.\.venv\Scripts\activate
uv pip install mcp-contextforge-gateway

# 后续继续执行上述第 2️⃣ 到 4️⃣ 步即可...

更多配置项说明 将 https://github.com/IBM/mcp-context-forge/blob/main/.env.example 复制为 .env，即可自定义调整所有配置项（也可直接将配置项作为环境变量使用）。

🚀 端到端演示（注册本地 MCP 服务器）

# 1️⃣ 使用 mcpgateway.translate 与 Docker 启动示例 MCP 时间服务器（如需可将 docker 替换为 podman）
python3 -m mcpgateway.translate \
--stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" \
--expose-sse \
--port 8003

# 也可通过 uvx 使用官方 mcp-server-git：
pip install uv # 若未安装 uvx 请先执行此命令安装 uv
python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9000

# 新特性：同时通过多种协议对外暴露服务！
python3 -m mcpgateway.translate \
--stdio "uvx mcp-server-git" \
--expose-sse \
--expose-streamable-http \
--port 9000
# 此时可通过 /sse（SSE 协议）和 /mcp（流式 HTTP 协议）两个端点同时访问

# 2️⃣ 将该服务器注册到网关
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"fast_time","url":"http://localhost:8003/sse"}' \
http://localhost:4444/servers

# 3️⃣ 验证工具目录
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq

# 4️⃣ 创建 *虚拟服务器* 聚合指定工具。使用第 3 步工具目录中获取的工具 ID，填入 associatedTools 列表
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":[ ]}}' \
http://localhost:4444/servers | jq

# 示例 curl 调用
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

# 5️⃣ 列出所有服务器（返回结果中应包含新创建虚拟服务器的 UUID）
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers | jq

# 6️⃣ 访问客户端 HTTP 端点。可通过 MCP Inspector CLI 交互式检查该端点（也可使用任意 MCP 客户端）
npx -y @modelcontextprotocol/inspector
# 传输类型选择：Streamable HTTP，URL 填写：http://localhost:4444/servers/UUID_OF_SERVER_1/mcp，请求头名称填写："Authorization"，再输入 Bearer 令牌即可

---

容器快速入门

可直接通过 Docker 或 Podman 使用 GHCR 上的官方 OCI 镜像。 请注意：当前生产版本暂不支持 arm64 架构。如果你使用搭载 Apple Silicon 芯片（M1、M2 等）的 MacOS 设备，可通过 Rosetta 运行容器，或改用 PyPI 方式安装。

🚀 Docker Compose 快速入门

[!IMPORTANT] docker compose up -d 默认不会在本地构建网关镜像，而是直接使用 GHCR 上的预构建镜像。Compose 文件中虽然包含 build: 块作为兜底，但本地构建需要 CI 流水线生成的封闭 wheel 依赖包。如果构建过程中出现 cryptography 或依赖解析错误，就是触发了该限制——直接拉取官方镜像即可，下方第 2 步会自动完成该操作。

同时你必须在运行 docker compose up -d 前准备好包含真实密钥的 .env 文件，网关无法在占位符配置下正常启动。

可通过以下步骤快速启动包含 PostgreSQL 和 Redis 的完整技术栈：

# 1️⃣ 克隆代码仓库
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# 2️⃣ 配置带真实密钥的 .env 并拉取预构建镜像
cp .env.example .env
python3 -m mcpgateway.scripts.init_secrets --patch-env .env
# 此时 .env 文件已包含高强度的 JWT_SECRET_KEY 和 AUTH_ENCRYPTION_SECRET

# 从 GHCR 拉取预构建镜像（完全跳过本地构建流程）
docker pull ghcr.io/ibm/mcp-context-forge:latest
echo 'IMAGE_LOCAL=ghcr.io/ibm/mcp-context-forge:latest'
>> .env

# 仅构建 nginx 镜像（体积小、仅本地可用，数秒即可完成构建）
docker compose build nginx

# 3️⃣ 启动完整技术栈
docker compose up -d

# 4️⃣ 检查运行状态
docker compose ps

# 5️⃣ 查看运行日志
docker compose logs -f gateway

# 6️⃣ 访问管理后台：http://localhost:8080/admin
# 登录账号：PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD（值从 .env 中读取）

# 7️⃣ 生成 API 令牌
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY"

您将获得以下组件：

• 🗄️ PostgreSQL - 已投入生产就绪的数据库，内含 55+ 张数据表
• 🚀 ContextForge - 功能完备的网关，自带管理后台 UI
• 📊 Redis - 高性能缓存与会话存储组件
• 🔧 管理工具 - pgAdmin、Redis Insight，用于数据库管理
• 🌐 Nginx 代理 - 运行在 8080 端口的缓存反向代理

启用 HTTPS（可选）：

# 启用 TLS 启动（将自动生成自签名证书）
make compose-tls

# 通过 HTTPS 访问：https://localhost:8443/admin

# 也可使用您自有证书：
# 未加密密钥场景：
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-key.pem certs/key.pem
make compose-tls

# 受密码保护的加密密钥场景：
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-encrypted-key.pem certs/key-encrypted.pem
echo "KEY_FILE_PASSWORD=your-passphrase"
>> .env
make compose-tls

☸️ 快速入门 - Helm（Kubernetes）

可使用企业级特性将其部署到 Kubernetes 环境：

# 添加 Helm 仓库（待可用时）
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# helm repo update

# 当前版本请使用本地 Chart
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack

# 首先生成密钥
python3 -m mcpgateway.scripts.init_secrets
JWT_SECRET=$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)
ENC_SECRET=$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)

# 使用 PostgreSQL 安装（默认配置）
# 重要提示：请替换为真实密码 —— 生产环境请勿使用 'changeme'
helm install mcp-gateway . \
--set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
--set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD= \
--set mcpContextForge.secret.BASIC_AUTH_PASSWORD= \
--set "mcpContextForge.secret.JWT_SECRET_KEY=${JWT_SECRET}" \
--set "mcpContextForge.secret.AUTH_ENCRYPTION_SECRET=${ENC_SECRET}"

# 检查部署状态
kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

# 端口转发以访问管理后台 UI
kubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80
# 访问地址：http://localhost:4444/admin

# 生成 API 令牌（从 Pod 环境中读取 JWT_SECRET_KEY）
kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
python3 -m mcpgateway.utils.create_jwt_token \
--username admin@yourcompany.com --exp 10080 --secret "${JWT_SECRET}"

[!NOTE] 关于 SSRF 的说明：Helm 默认采用严格的 SSRF 配置（SSRF_ALLOW_PRIVATE_NETWORKS=false）。 若您需要注册集群内工具 URL，请仅通过 mcpContextForge.config.SSRF_ALLOWED_NETWORKS 配置项放行您的集群 CIDR；仅在本地基准测试场景下，可临时设置 SSRF_ALLOW_PRIVATE_NETWORKS=true。 更多详情请参考 docs/docs/manage/configuration.md#ssrf-protection 与 docs/docs/deployment/helm.md。

企业级特性：

• 🔄 自动扩缩容 - 基于 CPU/内存指标的 HPA 自动扩缩容机制
• 🗄️ 数据库选型 - 支持 PostgreSQL（生产环境）、SQLite（开发环境）
• 📊 可观测性 - 提供 Prometheus 指标、OpenTelemetry 链路追踪
• 🔒 安全能力 - RBAC 权限控制、网络策略、密钥管理
• 🚀 高可用性 - 基于 Redis 集群的多副本部署方案
• 📈 监控体系 - 内置 Grafana 仪表盘与告警规则

---

🐳 Docker（单容器部署）

# 首先生成密钥（将创建 .env.secrets 文件）
python3 -m mcpgateway.scripts.init_secrets
export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"

docker run -d --name mcpgateway \
-p 4444:4444 \
-e MCPGATEWAY_UI_ENABLED=true \
-e MCPGATEWAY_ADMIN_API_ENABLED=true \
-e HOST=0.0.0.0 \
-e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
-e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
-e AUTH_REQUIRED=true \
-e PLATFORM_ADMIN_EMAIL=admin@example.com \
-e PLATFORM_ADMIN_PASSWORD= \
-e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
-e DATABASE_URL=sqlite:///./mcp.db \
-e SECURE_COOKIES=false \
ghcr.io/ibm/mcp-context-forge:latest

# 跟踪实时日志
docker logs -f mcpgateway

# 生成 API 令牌（使用与实例一致的密钥）
docker run --rm -it \
-e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
ghcr.io/ibm/mcp-context-forge:latest \
python3 -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}"

访问 **http://localhost:4444/admin**，使用您设置的 PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD 登录。

进阶配置：持久化存储、主机网络模式、离线隔离部署

持久化 SQLite 数据库：

mkdir -p $(pwd)/data && touch $(pwd)/data/mcp.db && chmod 777 $(pwd)/data
docker run -d --name mcpgateway --restart unless-stopped \
-p 4444:4444 -v $(pwd)/data:/data \
-e DATABASE_URL=sqlite:////data/mcp.db \
-e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \
-e HOST=0.0.0.0 -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
-e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
-e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD= \
ghcr.io/ibm/mcp-context-forge:latest

主机网络模式（用于访问本地 MCP 服务器）：

docker run -d --name mcpgateway --network=host \
-v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
-e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \
-e JWT_SECRET_KEY="${JWT_SECRET_KEY}" -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
ghcr.io/ibm/mcp-context-forge:latest

离线隔离部署（无互联网连接环境）：

docker build -f Containerfile -t mcpgateway:airgapped .
docker run -d --name mcpgateway -p 4444:4444 \
-e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \
-e HOST=0.0.0.0 -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
-e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
mcpgateway:airgapped

---

🦭 Podman（兼容无 root 用户场景）

podman run -d --name mcpgateway \
-p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:///./mcp.db \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

进阶配置：持久化存储、主机网络模式

持久化 SQLite：

mkdir -p $(pwd)/data && chmod 777 $(pwd)/data
podman run -d --name mcpgateway --restart=on-failure \
-p 4444:4444 -v $(pwd)/data:/data \
-e DATABASE_URL=sqlite:////data/mcp.db \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

主机网络模式：

podman run -d --name mcpgateway --network=host \
-v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

---

✏️ Docker/Podman 使用提示

• .env 文件 - 您可以将所有 -e FOO= 配置项存入单独文件中，替换为 --env-file .env 加载参数，可参考项目提供的 https://github.com/IBM/mcp-context-forge/blob/main/.env.example 作为模板。
• 固定镜像标签 - 建议使用明确的版本号（例如 1.0.0-RC-3）而非 latest 作为镜像标签，以保证部署可复现。
• JWT 令牌生成 - 您也可以在运行中的容器内直接生成令牌（该方式可自动从容器环境读取密钥）：

docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}"

• 升级操作 — 停止并删除现有容器，使用相同的 -v $(pwd)/data:/data 挂载参数重新运行，您的数据库和配置数据将完整保留。

---

🚑 对运行中的容器执行冒烟测试

curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
http://localhost:4444/health | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
http://localhost:4444/tools | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
http://localhost:4444/version | jq

---

快速入门：VS Code 开发容器

克隆代码仓库后在 VS Code 中打开项目，编辑器将自动检测到 .devcontainer 配置，并提示您点击 "在容器中重新打开"。该开发容器已预装 Python 3.11、Docker CLI 以及所有项目依赖项。

如需详细的搭建指南、工作流程说明与 GitHub Codespaces 使用教程，请参阅 **https://ibm.github.io/mcp-context-forge/development/developer-onboarding/**。

---

安装

make venv install-dev # 创建 .venv 虚拟环境 + 安装依赖 + 构建管理后台界面
make serve # 通过 gunicorn 启动服务，监听 4444 端口

Rust 工作区说明：

• 由工作区管理的 Rust crate 存放在 crates/ 目录下，根目录的 Cargo.toml 会通过 crates/* 自动加载这些组件。
• 在代码仓库根目录执行 cargo build、cargo test 和 cargo check 命令，即可覆盖整个共享工作区的操作。
• make venv install-dev 命令会在根目录创建 .venv 虚拟环境，该环境也会被工作区下的 PyO3/maturin 构建流程复用。

替代方案：使用 UV 或 pip 安装依赖

# 使用 UV（速度更快）
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'

# 使用 pip
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

PostgreSQL 适配器配置

请为 PostgreSQL 安装 psycopg 驱动：

# 先安装系统级依赖
# Debian/Ubuntu: sudo apt-get install libpq-dev
# macOS: brew install libpq

uv pip install 'psycopg[binary]' # 开发环境（使用预构建二进制包）
# 或执行：uv pip install 'psycopg[c]' # 生产环境（需要本地编译环境）

连接 URL 格式：

DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/mcp

快速启动 PostgreSQL 容器：

docker run --name mcp-postgres \
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword \
-e POSTGRES_DB=mcp -p 5432:5432 -d postgres

---

版本升级

升级操作说明、迁移指南与回滚流程请参考以下资源：

• https://ibm.github.io/mcp-context-forge/manage/upgrade/ — 通用升级操作流程
• MIGRATION.md — 不兼容变更说明与分步升级指引
• CHANGELOG.md — 版本历史与不兼容变更记录

---

配置

[!WARNING] 如果任何必需的 .env 变量缺失或无效，网关将在启动时通过 Pydantic 触发校验错误并快速失败，不会继续启动。

将项目提供的 https://github.com/IBM/mcp-context-forge/blob/main/.env.example 模板文件复制为 .env，并按要求更新以下涉及安全敏感信息的配置项。

🔐 必需配置：启动前必须设置

以下变量必须完成配置后网关才能正常启动，不存在可用的默认值：如果这些变量缺失或仍为占位值，应用程序将在启动阶段直接报错退出。

以下变量的默认值存在安全风险，在投入生产环境前必须修改：

🔒 安全默认配置（默认启用安全机制）

以下设置默认已出于安全原因开启，仅当需要兼容旧版本时才可禁用：

🛡️ 内容安全配置

内容大小限制可防范 DoS ***，保障系统运行稳定性：

[!NOTE] 该大小限制仅适用于新增/更新操作，不会对已存在的历史内容做回溯校验。

🌐 UAID 跨网关路由安全配置

UAID 安全配置规则

生产环境要求：

跨网关 UAID 路由功能必须完成显式安全配置才能使用：

1. 配置域名白名单：

UAID_ALLOWED_DOMAINS=["gateway1.example.com", "gateway2.example.com"]

2. 确保 JWT 信任关系：

• 所有参与的网关必须信任相同的 JWT 签发方
• 方案 A：共享密钥（所有网关配置相同的 JWT_SECRET_KEY）
• 方案 B：联合身份认证（对接 Google、GitHub、Entra ID）

3. 启用身份校验：

AUTH_REQUIRED=true
UAID_FORWARD_AUTH=true

身份认证流程：

跨网关调用时会通过 Authorization 头转发用户的持有者令牌，远程网关将通过现有身份认证中间件校验令牌，全程保留原有 RBAC 权限上下文。

内置安全特性：

• ✅ 闭环默认机制：白名单为空时将完全阻断所有跨网关路由请求
• ✅ 持有者令牌转发：用户身份认证状态在跨节点跳转中保持完整
• ✅ 审计追踪：请求源网关与用户信息将在请求头中留痕记录
• ✅ 明确错误提示：配置错误将在启动阶段与运行阶段被及时捕获并提示

故障排查：

• 出现 "UAID_ALLOWED_DOMAINS not configured" 错误：请在 .env 文件中添加受信任的网关域名到白名单
• 从远程网关收到 401/403 响应：请确认两个网关配置了相同信任的 JWT 签发方
• 出现 "proceeding without authentication token" 警告：请检查身份认证中间件是否正确将令牌解析到 request.state.bearer_token 变量中

如需了解完整的安全架构详情，请参考 docs/security/uaid-cross-gateway-auth.md 文档。

⚙️ 项目默认配置（开发环境设置）

以下配置项的取值与代码内置默认值不同，用于提供开箱可用的本地开发环境：

📚 完整配置参考

如需查看按类别（身份认证、缓存、SSO、可观测性等）组织的 300 余个环境变量完整列表，请参阅 **https://ibm.github.io/mcp-context-forge/manage/configuration/**。

---

运行方式

快速参考

开发服务器（Uvicorn）

make dev # Uvicorn 运行于 8000 端口，启用自动重载，使用 SQLite
# 或
./run.sh --reload --log debug --workers 2

run.sh 是 uvicorn 的封装脚本，会自动加载 .env 文件，支持重载配置，并将所有参数透传给服务器。

关键参数说明：

生产服务器（Gunicorn）

make serve # Gunicorn 运行于 4444 端口，启用多工作进程
make serve-ssl # 启用 HTTPS 的 Gunicorn，运行于 4444 端口（证书使用 ./certs 目录下的文件）

Docker Compose（完整技术栈）

make compose-up # 启动完整栈：PostgreSQL、Redis、3 个网关副本、Nginx 运行于 8080 端口
make compose-sso # 启动包含 Keycloak 的 SSO 栈，Keycloak 运行于 8180 端口
make sso-test-login # 运行 SSO 冒烟检查（覆盖身份提供商、登录 URL、测试用户场景）
make compose-logs # 追踪所有服务的日志
make compose-down # 停止整个技术栈

手动启动（Uvicorn）

uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4

---

云平台部署

ContextForge 可部署至所有主流云平台：

如需查阅完整部署指南，请访问 **https://ibm.github.io/mcp-context-forge/deployment/**。

---

API 参考

服务器运行后，你可以访问交互式 API 文档：

• http://localhost:4444/docs — 直接在浏览器中尝试调用 API
• http://localhost:4444/redoc — 浏览完整的端点参考

快速身份认证流程：

# 从 .env 文件中读取 JWT_SECRET_KEY（该文件需已提前配置合法的密钥值）
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)

# 生成 JWT 令牌
export TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")

# 测试 API 访问权限
curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/health

如需查阅覆盖所有端点的完整 curl 示例，请参考 **https://ibm.github.io/mcp-context-forge/manage/api-usage/**。

---

测试

make test # 运行单元测试
make lint # 运行所有代码检查工具
make doctest # 运行文档测试
make coverage # 生成测试覆盖率报告

关于文档测试的详细说明，请参阅 https://ibm.github.io/mcp-context-forge/development/doctest-coverage/。

---

项目结构

mcpgateway/ # 核心 FastAPI 应用
├── main.py # 程序入口
├── config.py # Pydantic 配置项定义
├── db.py # SQLAlchemy ORM 模型
├── schemas.py # Pydantic 校验 schema
├── services/ # 业务逻辑层（包含 50+ 个服务模块）
├── routers/ # HTTP 端点定义
├── middleware/ # 横切关注点组件
└── transports/ # SSE、WebSocket、stdio、流式 HTTP 传输实现

tests/ # 测试套件（包含 7000+ 个测试用例）
docs/docs/ # 完整文档（基于 MkDocs 构建）
charts/ # Kubernetes/Helm 图表
plugins/ # 插件框架与内置插件实现

[!IMPORTANT] 安全提示：永远不要在本地文件系统上直接运行不受信任的 MCP 服务器。请始终使用沙箱、容器或微虚拟机（例如 gVisor、Fire***er）并限制其权限。注册任何远程 MCP 服务器时务必谨慎，包括来自公共目录的服务器 — 在为其授予网关访问权限前，请自行完成安全评估。

如需查看完整项目结构，请参阅 CONTRIBUTING.md 或执行 tree -L 2 命令。

---

开发相关

make dev # 启动自动重载的开发服务器（运行于 8000 端口）
make test # 运行测试套件
make lint # 运行所有代码检查工具
make coverage # 生成测试覆盖率报告

直接执行 make 命令即可查看所有可用的 Make 目标。

如需了解完整开发工作流，请参考：

• https://ibm.github.io/mcp-context-forge/development/developer-workstation/
• https://ibm.github.io/mcp-context-forge/development/building/

---

故障排除

常见问题与解决方案：

.env后重试 | | 执行docker compose up时报错SecurityConfigurationError: jwt_secret_key|.env文件缺失，或文件内仍存在REPLACE_ME占位符。执行cp .env.example .env && python3 -m mcpgateway.scripts.init_secrets --patch-env .env| | 执行docker compose up时报错，提示拉取mcpgateway/nginx-cache镜像权限被拒绝 | 必须在本地构建 nginx 镜像：执行docker compose build nginx| | 执行make dev后，8000 端口无服务响应 | 查看终端输出是否存在SecurityConfigurationError，先执行 make ensure-secrets再重试。如果使用 WSL2 环境，请访问http://127.0.0.1:8000`，不要使用 localhost | | macOS 系统下出现 SQLite "disk I/O error" 磁盘I/O错误 | 请勿使用iCloud同步的目录，改用路径 ~/mcp-context-forge/data | | WSL2 环境下 4444 端口无法访问 | 在 Docker Desktop 中配置 WSL 集成 | | 网关进程立即退出 | 执行 cp .env.example .env && python3 -m mcpgateway.scripts.init_secrets --patch-env .env | | 出现 ModuleNotFoundError 模块未找到错误 | 执行 make install-dev |

如需查看详细的故障排查指南，请访问 **https://ibm.github.io/mcp-context-forge/manage/troubleshooting/**。

---

贡献指南

1. Fork 该代码仓库，新建一个特性分支。
2. 运行 make lint 并修复所有检测出的问题。
3. 确保 make test 所有测试用例全部通过。
4. 提交 PR 时请使用签名提交（执行 git commit -s）。

完整规范请查看 CONTRIBUTING.md，如需了解提交缺陷报告、提出功能需求、认领待处理问题的方式，请参考 **https://github.com/IBM/mcp-context-forge/issues/2502**。

---

更新日志

完整的更新日志请查阅：CHANGELOG.md

许可证

本项目采用 Apache License 2.0 许可协议 — 具体内容请查看 LICENSE 文件。

核心作者与维护者

• Mihai Criveti — 杰出工程师，专注于智能体AI领域

特别感谢所有帮助我们优化 ContextForge 的贡献者：

Star 历史与项目活跃度