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 部署，并可在 Kubernetes 上通过 Redis 支持的联邦和缓存机制扩展到多集群环境。

目录

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

📌 快速链接

概述与目标

ContextForge 是一个开源注册表和代理，可联合任何 模型上下文协议 (MCP) 服务器、A2A 服务器或 REST/gRPC API，提供集中式治理、发现和可观测性。它优化了代理和工具调用，并支持插件。更多详情请参阅项目路线图。

目前支持：

• 跨多个 MCP 和 REST 服务的联邦
• A2A（代理到代理）集成，用于外部 AI 代理（OpenAI、Anthropic、自定义）
• gRPC 到 MCP 的转换，通过自动反射式服务发现实现
• 将遗留 API 虚拟化为符合 MCP 标准的工具和服务器
• 支持 HTTP、JSON-RPC、WebSocket、SSE（可配置保持连接）、stdio 和可流式传输的 HTTP 等传输方式
• 管理员 UI，用于实时管理、配置和日志监控（支持气隙部署）
• 内置身份验证、重试和限流功能，支持用户范围内的 OAuth 令牌以及无条件的 X-Upstream-Authorization 头
• OpenTelemetry 可观测性，支持 Phoenix、Jaeger、Zipkin 等 OTLP 后端
• 通过 Docker 或 PyPI、基于 Redis 的缓存以及多集群联邦实现可扩展部署

有关即将推出的功能列表，请查看ContextForge 路线图。

快速入门 - PyPI

ContextForge 已在 PyPI 上发布，包名为 mcp-contextforge-gateway。

简而言之；： （使用 uv 的单条命令）

# 使用环境变量快速启动
BASIC_AUTH_PASSWORD=pass \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
PLATFORM_ADMIN_PASSWORD=changeme \
PLATFORM_ADMIN_FULL_NAME="平台管理员" \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

# 或者更好：使用提供的 .env.example
cp .env.example .env
# 编辑 .env 以自定义您的设置
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

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️⃣ 复制并定制配置
# 下载示例环境文件
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env
# 编辑 .env 以自定义您的设置（尤其是密码！）

# 或直接设置环境变量：
export MCPGATEWAY_UI_ENABLED=true
export MCPGATEWAY_ADMIN_API_ENABLED=true
export PLATFORM_ADMIN_EMAIL=admin@example.com
export PLATFORM_ADMIN_PASSWORD=changeme
export PLATFORM_ADMIN_FULL_NAME="平台管理员"

BASIC_AUTH_PASSWORD=pass JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
  mcpgateway --host 0.0.0.0 --port 4444 &   # admin/pass

# 3️⃣ 生成 Bearer 令牌并进行 API 冒烟测试
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)

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

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

# 2️⃣ 复制并定制配置
# 下载示例环境文件
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env
# 编辑 .env 以自定义您的设置

# 或设置会话级别的环境变量
$Env:MCPGATEWAY_UI_ENABLED        = "true"
$Env:MCPGATEWAY_ADMIN_API_ENABLED = "true"
# 注意：API 的基本认证默认是关闭的（API_ALLOW_BASIC_AUTH=false）
$Env:JWT_SECRET_KEY               = "my-test-key-but-now-longer-than-32-bytes"
$Env:PLATFORM_ADMIN_EMAIL         = "admin@example.com"
$Env:PLATFORM_ADMIN_PASSWORD      = "changeme"
$Env:PLATFORM_ADMIN_FULL_NAME     = "平台管理员"

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

#   可选：将其置于后台

# 使用 Start-Process 启动 mcpgateway.exe，并传递参数 --host 0.0.0.0 --port 4444

# 4️⃣ Bearer 令牌与冒烟测试
$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

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

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

# 继续执行上述步骤 2️⃣-4️⃣...

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

# 或者使用官方的 mcp-server-git，通过 uvx：
pip install uv # 如果尚未安装，先安装 uvx
python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9000

# 另一种方式：运行本地二进制文件
# cd mcp-servers/go/fast-time-server; make build
# python3 -m mcpgateway.translate --stdio "./dist/fast-time-server -transport=stdio" --expose-sse --port 8002

# 新功能：同时支持多种协议！
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/gateways

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

# 4️⃣ 创建一个*虚拟服务器*，将这些工具捆绑在一起。使用工具目录中的工具 ID（步骤 #3），并将其放入 associatedTools 列表中。
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"server":{"name":"time_server","description":"快速时间工具","associated_tools":[<工具ID>]}}' \
     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":"快速时间工具","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
# 传输类型：流式 HTTP，URL：http://localhost:4444/servers/服务器UUID_1/mcp，头名称：“Authorization”，Bearer 令牌

export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
export MCP_SERVER_URL=http://localhost:4444/servers/服务器UUID_1/mcp
python3 -m mcpgateway.wrapper  # 按 Ctrl-C 退出

echo $PWD/.venv/bin/python3 # 使用 Python3 的完整路径可以确保你有一个可用的虚拟环境
export MCP_SERVER_URL='http://localhost:4444/servers/服务器UUID_1/mcp'
export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
npx -y @modelcontextprotocol/inspector

npx -y @modelcontextprotocol/inspector
命令设为 `python`
参数设为 `-m mcpgateway.wrapper --url "http://localhost:4444/servers/服务器UUID_1/mcp" --auth "Bearer <你的令牌>"`

{
  "mcpServers": {
    "mcpgateway-wrapper": {
      "command": "python",
      "args": ["-m", "mcpgateway.wrapper"],
      "env": {
        "MCP_AUTH": "Bearer 你的令牌",
        "MCP_SERVER_URL": "http://localhost:4444/servers/服务器UUID_1",
        "MCP_TOOL_CALL_TIMEOUT": "120"
      }
    }
  }
}

快速入门 - 容器

使用 GHCR 上的官方 OCI 镜像，搭配 Docker 或 Podman。 请注意：目前生产环境中不支持 arm64 架构。如果你正在使用搭载 Apple Silicon 芯片的 Mac 设备（如 M1、M2 等），可以使用 Rosetta 运行容器，或者直接通过 PyPI 安装替代方案。

🚀 快速入门 - Docker Compose

在不到 30 秒内启动包含 PostgreSQL 和 Redis 的完整堆栈：

# 克隆并启动堆栈
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# 首先启动 PostgreSQL（推荐用于生产环境）
docker compose up -d

# 检查状态
docker compose ps

# 查看日志
docker compose logs -f gateway

# 访问管理界面：http://localhost:8080/admin（使用 PLATFORM_ADMIN_EMAIL/PASSWORD 登录）
# 生成 API 令牌
docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

你将获得：

• 🗄️ PostgreSQL - 生产就绪的数据库，包含 55+ 张表
• 🚀 ContextForge - 功能齐全的网关，附带管理界面
• 📊 Redis - 高性能缓存与会话存储
• 🔧 管理工具 - pgAdmin、Redis Insight，用于数据库管理
• 🌐 Nginx 代理 - 缓存反向代理，运行在 8080 端口

启用 HTTPS（可选）：

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

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

# 或者使用你自己的证书：
# 未加密的密钥：
mkdir -p certs
cp 你的-cert.pem certs/cert.pem && cp 你的-key.pem certs/key.pem
make compose-tls

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

☸️ 快速入门 - Helm（Kubernetes）

部署到 Kubernetes，享受企业级功能：

# 添加 Helm 仓库（待上线时）

# 添加 Helm 仓库 mcp-context-forge
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# 更新 Helm 仓库
# helm repo update

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

# 使用 PostgreSQL 安装（默认）
helm install mcp-gateway . \
  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \
  --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key

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

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

# 生成 API 令牌
kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
  python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@yourcompany.com --exp 10080 --secret your-secret-key

SSRF 注意：Helm 默认启用严格的 SSRF 设置（SSRF_ALLOW_PRIVATE_NETWORKS=false）。 如果您注册集群内工具 URL（例如 fast-time 或 fast-test 服务），请仅通过 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（单容器）

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=my-test-key-but-now-longer-than-32-bytes \
  -e AUTH_REQUIRED=true \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com \
  -e PLATFORM_ADMIN_PASSWORD=changeme \
  -e PLATFORM_ADMIN_FULL_NAME="平台管理员" \
  -e DATABASE_URL=sqlite:///./mcp.db \
  -e SECURE_COOKIES=false \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

# 查看日志并生成 API 密钥
docker logs -f mcpgateway
docker run --rm -it ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2 \
  python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

浏览至 http://localhost:4444/admin，使用 PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD 登录。

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=my-test-key-but-now-longer-than-32-bytes \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=changeme \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

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 \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2

docker build -f Containerfile.lite -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=my-test-key-but-now-longer-than-32-bytes \
  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-2

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-2

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-2

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

# 设置环境变量
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)
export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'
export MCP_TOOL_CALL_TIMEOUT=120
export MCP_WRAPPER_LOG_LEVEL=DEBUG  # 或 OFF 关闭日志记录

docker run --rm -i \
  -e MCP_AUTH=$MCP_AUTH \
  -e MCP_SERVER_URL=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1/mcp \
  -e MCP_TOOL_CALL_TIMEOUT=120 \
  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-2 \
  python3 -m mcpgateway.wrapper

快速入门：VS Code 开发容器

克隆仓库并在 VS Code 中打开——它会检测到 .devcontainer 文件并提示选择 “在容器中重新打开”。该容器包含 Python 3.11、Docker CLI 以及项目的所有依赖项。

有关详细设置、工作流和 GitHub Codespaces 的说明，请参阅 开发者入职指南。

安装

make venv install          # 创建 .venv 并安装依赖
make serve                 # 使用 gunicorn 在 :4444 端口运行

# 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]"

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

uv pip install 'psycopg[binary]'   # 开发环境（预编译的 wheel 包）
# 或者：uv pip install 'psycopg[c]'  # 生产环境（需要编译器）

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

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

升级

有关升级说明、迁移指南和回滚流程，请参阅：

• 升级指南 — 通用升级流程
• CHANGELOG.md — 版本历史及破坏性变更
• MIGRATION-0.7.0.md — 多租户迁移（v0.6.x → v0.7.x）

配置

⚠️ 如果任何必需的 .env 变量缺失或无效，网关将在启动时通过 Pydantic 的验证错误快速失败。

将提供的 .env.example 复制到 .env 文件中，并更新以下安全敏感值。

🔐 必须在使用前更改

这些变量具有不安全的默认值，必须在生产部署前更改：

🔒 安全默认设置（默认安全）

这些设置默认启用以确保安全性——仅在需要向后兼容时才禁用：

🛡️ 内容安全限制

内容大小限制可防止 DoS 攻击并确保系统稳定性：

注意：大小限制仅适用于新的创建或更新操作。现有内容不会被追溯验证。

⚙️ 项目默认值（开发环境）

这些值与代码中的默认值不同，旨在提供一个可用的本地/开发环境：

📚 完整配置参考

有关按类别（认证、缓存、SSO、可观测性等）组织的 300 多个环境变量的完整列表，请参阅 配置参考。

运行

快速参考

开发服务器（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           # Gunicorn 后面启用 HTTPS，在 :4444 端口运行（使用 ./certs 目录下的证书）

Docker Compose（全栈部署）

make compose-up          # 启动全栈：PostgreSQL、Redis、3 个网关副本、Nginx 在 :8080 端口运行
make compose-sso         # 启动 SSO 栈，Keycloak 在 :8180 端口运行
make sso-test-login      # 运行 SSO 功能测试（身份提供商 + 登录 URL + 测试用户）
make compose-logs        # 实时查看所有服务的日志
make compose-down        # 停止整个栈

Manual (Uvicorn)

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

Cloud Deployment

ContextForge can be deployed to any major cloud platform:

For comprehensive deployment guides, see Deployment Documentation.

API Reference

Interactive API documentation is available when the server is running:

• Swagger UI — Try API calls directly in your browser
• ReDoc — Browse the complete endpoint reference

Quick Authentication:

# Generate a JWT token
export TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)

# Test API access
curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/health

For comprehensive curl examples covering all endpoints, see the API Usage Guide.

Testing

make test            # Run unit tests
make lint            # Run all linters
make doctest         # Run doctests
make coverage        # Generate coverage report

See Doctest Coverage Guide for documentation testing details.

Project Structure

mcpgateway/          # Core FastAPI application
├── main.py          # Entry point
├── config.py        # Pydantic Settings configuration
├── db.py            # SQLAlchemy ORM models
├── schemas.py       # Pydantic validation schemas
├── services/        # Business logic layer (50+ services)
├── routers/         # HTTP endpoint definitions
├── middleware/      # Cross-cutting concerns
└── transports/      # SSE, WebSocket, stdio, streamable HTTP

tests/               # Test suite (7,000+ tests)
docs/docs/           # Full documentation (MkDocs)
charts/              # Kubernetes/Helm charts
plugins/             # Plugin framework and implementations
mcp-servers/         # Sample/test MCP servers (see note below)

Note: The mcp-servers/ directory contains unsupported sample and test servers, most originating from community contributions, provided for demonstration and integration testing purposes only. They generally lack session management, persistent state, multi-tenancy, authentication, and other production concerns. They do not go through the same review, testing, and security rigor as the core ContextForge codebase and should not be run in production.

Security: Never run untrusted MCP servers directly on your local filesystem. Always use a sandbox, container, or microVM (e.g. gVisor, Firecracker) with restricted capabilities. Exercise caution when registering any remote MCP server, including servers from public catalogs — perform your own security evaluation before granting access to your gateway.

For complete structure, see CONTRIBUTING.md or run tree -L 2.

Development

make dev             # Dev server with auto-reload (:8000)
make test            # Run test suite
make lint            # Run all linters
make coverage        # Generate coverage report

Run make to see all available targets.

For development workflows, see:

• Developer Workstation Setup
• Building & Packaging

Troubleshooting

Common issues and solutions:

For detailed troubleshooting guides, see Troubleshooting Documentation.

Contributing

1. Fork the repo, create a feature branch.
2. Run make lint and fix any issues.
3. Keep make test green.
4. Open a PR with signed commits (git commit -s).

See CONTRIBUTING.md for full guidelines and Issue Guide #2502 for how to file bugs, request features, and find issues to work on.

Changelog

A complete changelog can be found here: CHANGELOG.md

License

Licensed under the Apache License 2.0 - see LICENSE

Core Authors and Maintainers

• Mihai Criveti - Distinguished Engineer, Agentic AI

Special thanks to our contributors for helping us improve ContextForge:

Star History and Project Activity

ContextForge 快速上手指南

ContextForge 是一个开源的注册中心和代理网关，旨在将 MCP、A2A 以及 REST/gRPC API 联邦化，为 AI 客户端提供统一的接入点。它支持集中式治理、服务发现、可观测性，并优化了 Agent 与工具的调用流程。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (PowerShell)
• Python 版本：≥ 3.11
• 可选工具：
  • uv：推荐的极速 Python 包管理器和运行器（比 pip 更快）。
  • curl 和 jq：用于后续的服务健康检查测试。

国内加速建议： 如果使用 pip 安装，建议配置国内镜像源以提升下载速度：

export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 或在命令中临时指定：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...

安装步骤

您可以选择使用 uv（推荐，单命令启动）或传统的 pip + 虚拟环境方式。

方式一：使用 uv 快速启动（推荐）

无需手动创建虚拟环境，uvx 会自动处理依赖隔离。

# 1. 复制示例配置文件并自定义（可选但推荐）
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env
# 编辑 .env 文件修改密码等敏感信息

# 2. 直接运行网关
# 注意：首次运行会自动下载 mcp-contextforge-gateway 包
BASIC_AUTH_PASSWORD=pass \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
PLATFORM_ADMIN_PASSWORD=changeme \
PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

方式二：使用 pip 和虚拟环境

适合需要长期开发或深度定制的场景。

# 1. 创建项目目录和虚拟环境
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv

# 激活虚拟环境
# Linux/macOS:
source .venv/bin/activate
# Windows (PowerShell):
# .\.venv\Scripts\Activate.ps1

# 2. 升级 pip 并安装 ContextForge
pip install --upgrade pip
pip install mcp-contextforge-gateway
# 国内用户可使用：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcp-contextforge-gateway

# 3. 配置环境变量
# 方法 A: 导出变量到当前会话
export MCPGATEWAY_UI_ENABLED=true
export MCPGATEWAY_ADMIN_API_ENABLED=true
export PLATFORM_ADMIN_EMAIL=admin@example.com
export PLATFORM_ADMIN_PASSWORD=changeme
export PLATFORM_ADMIN_FULL_NAME="Platform Administrator"
export JWT_SECRET_KEY="my-test-key-but-now-longer-than-32-bytes"

# 方法 B: 或者直接使用 .env 文件 (需确保代码支持加载)
# curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
# cp .env.example .env

# 4. 启动服务
mcpgateway --host 0.0.0.0 --port 4444

基本使用

服务启动后，默认监听在 http://0.0.0.0:4444。以下是验证服务和获取访问令牌的最简流程。

1. 生成访问令牌 (Bearer Token)

ContextForge 默认使用 JWT 进行认证。使用内置工具生成一个临时令牌：

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin@example.com \
    --exp 10080 \
    --secret my-test-key-but-now-longer-than-32-bytes)

Windows PowerShell 用户请使用以下命令生成令牌：

$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

2. 测试 API 连通性

使用 curl 请求版本接口，确认服务正常运行：

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

如果返回类似 {"version": "..."} 的 JSON 数据，说明网关已成功启动。

3. 访问管理后台

如果在启动时设置了 MCPGATEWAY_UI_ENABLED=true，您可以直接在浏览器中访问管理界面：

• 地址: http://localhost:4444/
• 登录账号: 您在环境变量中设置的 PLATFORM_ADMIN_EMAIL (例如: admin@example.com)
• 登录密码: 您设置的 PLATFORM_ADMIN_PASSWORD (例如: changeme)

在管理后台中，您可以注册新的 MCP 服务器、配置 REST API 映射、查看实时日志以及管理插件。