MCP Gateway

ContextForge

一个开源注册表和代理，可联合 MCP、A2A 和 REST/gRPC API，并提供集中式治理、发现和可观测性。优化 Agent 和工具调用，并支持插件。

ContextForge 是一个开源注册表和代理，可将工具、Agent 和 API 联合到一个简洁的端点，供 AI 客户端使用。它为 AI 基础设施提供集中式治理、发现和可观测性：

• 工具网关 — MCP、REST、gRPC 到 MCP 的转换，以及 TOON 压缩
• Agent 网关 — A2A 协议、兼容 OpenAI 的路由和 Anthropic Agent 路由
• API 网关 — 为 REST 服务提供速率限制、身份验证、重试和反向代理
• 插件扩展性 — 40 多个插件，支持额外的传输方式、协议和集成
• 可观测性 — 使用 Phoenix、Jaeger、Zipkin 和其他 OTLP 后端进行 OpenTelemetry 跟踪

它以完全合规的 MCP 服务运行，可通过 PyPI 或 Docker 部署，并可借助 Redis 支持的联合与缓存，在 Kubernetes 上扩展至多集群环境。

目录

• 概览与目标
• 快速开始 - PyPI
• 快速开始 - 容器
  • 可选 Web UI
• VS Code 开发容器
• 安装
• 升级
• 配置
• 运行
• 云部署
• API 参考
• 测试
• 项目结构
• 开发
• 故障排查
• 贡献

📌 快速链接

概述与目标

ContextForge 是一个开源注册中心和代理，可联合接入任意 Model Context Protocol（MCP）服务、A2A 服务或 REST/gRPC API，并提供集中式治理、发现和可观测性。它可优化 Agent 和工具调用，并支持插件。详情请参阅项目路线图。

目前支持：

• 联合接入多个 MCP 和 REST 服务
• A2A（Agent-to-Agent）集成，支持外部 AI Agent（OpenAI、Anthropic、自定义）
• 通过基于反射的自动服务发现实现 gRPC 到 MCP 的转换
• 将旧版 API 虚拟化为符合 MCP 标准的工具和服务
• 支持通过 HTTP、JSON-RPC、WebSocket、SSE（可配置 keepalive）和 Streamable HTTP 传输；服务端可使用 stdio 传输
• 提供管理 UI，用于实时管理、配置和日志监控（支持隔离网络部署）
• 重新设计、更加易用的Web UI，在独立容器中运行
• 内置身份验证、重试和速率限制，支持用户级 OAuth 令牌以及无条件添加 X-Upstream-Authorization 标头
• OpenTelemetry 可观测性，支持 Phoenix、Jaeger、Zipkin 和其他 OTLP 后端
• 通过 Docker 或 PyPI、Redis 缓存和多集群联合部署实现可扩展部署

如需了解即将推出的功能，请查看 ContextForge 路线图

快速入门 - PyPI

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

⚠️ 所有环境都必须设置 JWT_SECRET_KEY 和 AUTH_ENCRYPTION_SECRET，包括本地开发环境。 缺少这些变量时，网关将无法启动。首次运行前，请使用 python3 -m mcpgateway.scripts.init_secrets 生成真实密钥。

简而言之——使用 uv 运行单条命令：

# 1️⃣  Generate secure secrets (creates .env.secrets)
python3 -m mcpgateway.scripts.init_secrets

# 2️⃣  Export the generated values
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️⃣  Start the gateway
JWT_SECRET_KEY="$JWT_SECRET_KEY" \
AUTH_ENCRYPTION_SECRET="$AUTH_ENCRYPTION_SECRET" \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
[email protected] \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

1 - 安装并运行（方便复制粘贴）

# 1️⃣  Create an isolated env and install from PyPI
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Download .env.example and generate real secrets
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Start the gateway
mcpgateway --host 0.0.0.0 --port 4444 &

# 4️⃣  Generate a bearer token and smoke-test
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username [email protected] --exp 10080 --secret "$JWT_SECRET_KEY")

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

# 1️⃣  Isolated env + install from PyPI
mkdir mcpgateway ; cd mcpgateway
python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Download .env.example and generate real secrets
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Launch the gateway
mcpgateway.exe --host 0.0.0.0 --port 4444

# 4️⃣  Bearer token and smoke-test
$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 [email protected] --exp 10080 --secret $Env:JWT_SECRET_KEY

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

# 1️⃣  Isolated env + install from PyPI using uv
mkdir mcpgateway ; cd mcpgateway
uv venv
.\.venv\Scripts\activate
uv pip install mcp-contextforge-gateway

# Continue with steps 2️⃣-4️⃣ above...

# 1️⃣  Spin up the sample MCP time server using mcpgateway.translate & docker (replace docker with podman if needed)
python3 -m mcpgateway.translate \
     --stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" \
     --expose-sse \
     --port 8003

# Or using the official mcp-server-git using uvx:
pip install uv # to install uvx, if not already installed
python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9000

# NEW: Expose via multiple protocols simultaneously!
python3 -m mcpgateway.translate \
     --stdio "uvx mcp-server-git" \
     --expose-sse \
     --expose-streamable-http \
     --port 9000
# Now accessible via both /sse (SSE) and /mcp (streamable HTTP) endpoints

# 2️⃣  Register it with the gateway
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️⃣  Verify tool catalog
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq

# 4️⃣  Create a *virtual server* bundling those tools. Use the ID of tools from the tool catalog (Step #3) and pass them in the associatedTools list.
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":[<ID_OF_TOOLS>]}}' \
     http://localhost:4444/servers | jq

# Example 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️⃣  List servers (should now include the UUID of the newly created virtual server)
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers | jq

# 6️⃣  Client HTTP endpoint. Inspect it interactively with the MCP Inspector CLI (or use any MCP client)
npx -y @modelcontextprotocol/inspector
# Transport Type: Streamable HTTP, URL: http://localhost:4444/servers/UUID_OF_SERVER_1/mcp,  Header Name: "Authorization", Bearer Token

快速入门 - 容器

使用 GHCR 上的官方 OCI 镜像，可选择 Docker 或 Podman。 请注意：目前生产环境不支持 arm64。如果你在搭载 Apple Silicon 芯片（M1、M2 等）的 MacOS 上运行，可以通过 Rosetta 运行容器，或改用 PyPi 安装。

🚀 快速入门 - Docker Compose

**重要提示：**默认情况下，docker compose up -d 不会在本地构建网关镜像，而是使用 GHCR 上预构建的镜像。compose 文件包含一个 build: 块作为备用方案，但本地构建需要由 CI 流水线生成的 hermetic wheel 闭包。如果构建时遇到 cryptography 或依赖项解析错误，就是这个原因——直接拉取镜像即可（下方步骤 2 会自动处理）。

运行 docker compose up -d 前，还必须准备好包含真实密钥的 .env 文件。使用占位值时，网关将无法启动。

使用 PostgreSQL 和 Redis 启动完整技术栈：

# 1️⃣  Clone the repository
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# 2️⃣  Set up .env with real secrets AND pull the pre-built images
cp .env.example .env
python3 -m mcpgateway.scripts.init_secrets --patch-env .env
# .env now has strong JWT_SECRET_KEY and AUTH_ENCRYPTION_SECRET

# Pull pre-built images from GHCR (avoids local build entirely)
docker pull ghcr.io/ibm/mcp-context-forge:latest
echo 'IMAGE_LOCAL=ghcr.io/ibm/mcp-context-forge:latest' >> .env

# Build only the nginx image (small, local-only, builds in seconds)
docker compose build nginx

# 3️⃣  Start the full stack
docker compose up -d

# 4️⃣  Check status
docker compose ps

# 5️⃣  View logs
docker compose logs -f gateway

# 6️⃣  Access Admin UI: http://localhost:8080/admin
#     Login: PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD (from .env)

# 7️⃣  Generate an API token
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
  --username [email protected] --exp 10080 --secret "$JWT_SECRET_KEY"

你将获得：

• 🗄️ PostgreSQL - 可用于生产环境的数据库，包含 55 张以上的表
• 🚀 ContextForge - 功能齐全且带有管理 UI 的网关
• 📊 Redis - 高性能缓存和会话存储
• 🔧 管理工具 - pgAdmin、Redis Insight，用于数据库管理
• 🌐 Nginx 代理 - 在端口 8080 上运行的缓存反向代理

启用 HTTPS（可选）：

# Start with TLS enabled (auto-generates self-signed certs)
make compose-tls

# Access via HTTPS: https://localhost:8443/admin

# Or bring your own certificates:
# Unencrypted key:
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-key.pem certs/key.pem
make compose-tls

# Passphrase-protected key:
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

可选 Web UI

ContextForge Web UI v0.2.4 提供了重新设计、更加易用的界面，与内置管理 UI 分开。 它在独立的容器中运行，并连接到网关 API。

完成上述 Docker Compose 设置后，在网关代码库目录中运行以下命令以启动 Web UI：

make compose-pull PROFILE="--profile ui"
make compose-up PROFILE="--profile ui"

打开 http://localhost:3001，并使用你的网关账户登录。 设置 .env 中的 WEB_UI_PORT 可更改端口。 ui 配置会启动 Web UI，并在网关旁启动其专用的 Redis 会话存储。

PROFILE 会替换 Makefile 的默认配置。 在 linux/amd64 上，请在两条命令中使用 PROFILE="--profile with-fast-time --profile ui"，以保留默认的 fast-time 服务。

如需单独配置 npm 开发环境，请参阅 Web UI 设置指南。

☸️ 快速开始 - Helm（Kubernetes）

使用企业级功能部署到 Kubernetes：

# Add Helm repository (when available)
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# helm repo update

# For now, use local chart
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack

# Generate secrets first
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)

# Install with PostgreSQL (default)
# IMPORTANT: replace <strong-password> with a real password — do not use 'changeme' in production
helm install mcp-gateway . \
  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=<strong-password> \
  --set mcpContextForge.secret.BASIC_AUTH_PASSWORD=<strong-password> \
  --set "mcpContextForge.secret.JWT_SECRET_KEY=${JWT_SECRET}" \
  --set "mcpContextForge.secret.AUTH_ENCRYPTION_SECRET=${ENC_SECRET}"

# Check deployment status
kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

# Port forward to access Admin UI
kubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80
# Access: http://localhost:4444/admin

# Generate API token (reads JWT_SECRET_KEY from the pod's environment)
kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
  python3 -m mcpgateway.utils.create_jwt_token \
  --username [email protected] --exp 10080 --secret "${JWT_SECRET}"

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（单容器）

# Generate secrets first (creates .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 [email protected] \
  -e PLATFORM_ADMIN_PASSWORD=<strong-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

# Tail logs
docker logs -f mcpgateway

# Generate API token (using the same secret)
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 [email protected] --exp 10080 --secret "${JWT_SECRET_KEY}"

访问 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="${JWT_SECRET_KEY}" \
  -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  -e [email protected] -e PLATFORM_ADMIN_PASSWORD=<strong-password> \
  ghcr.io/ibm/mcp-context-forge:latest

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

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

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 中打开——VS Code 会检测到 .devcontainer，并提示 “在容器中重新打开”。容器包含 Python 3.11、Docker CLI 和所有项目依赖项。

如需了解详细的设置步骤、工作流和 GitHub Codespaces 说明，请参阅 开发者入门指南。

安装

make venv install-dev      # create .venv + install deps + build Admin UI
make serve                 # gunicorn on :4444

Rust 工作区说明：

• 工作区自有的 Rust crate 位于 crates/ 下，并通过根目录的 Cargo.toml 中的 crates/* 纳入工作区。
• 请在仓库根目录运行 cargo build、cargo test 和 cargo check，以覆盖共享工作区。
• make venv install-dev 会创建根目录下的 .venv，工作区的 PyO3/maturin 构建也会复用该环境。

# UV (faster)
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'

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

# Install system dependencies first
# Debian/Ubuntu: sudo apt-get install libpq-dev
# macOS: brew install libpq

uv pip install 'psycopg[binary]'   # dev (pre-built wheels)
# or: uv pip install 'psycopg[c]'  # production (requires compiler)

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

升级

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

• 升级指南 — 常规升级流程
• MIGRATION.md — 重大变更和分步升级说明
• CHANGELOG.md — 版本历史和重大变更

配置

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

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

🔐 必填：启动前设置

网关启动前必须设置这些变量。它们没有可用的默认值——如果缺少这些变量或其值为占位符，应用将在启动时失败：

这些变量的默认值不安全，应在生产环境中使用前修改：

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

出于安全考虑，默认启用这些设置；仅为向后兼容时才禁用：

🛡️ 内容安全

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

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

🌐 UAID 跨网关路由安全

UAID 安全配置

生产环境要求：

跨网关 UAID 路由需要显式配置安全设置：

1. 配置域名允许列表：

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

2. 确保 JWT 信任关系：

   • 两个网关必须信任同一个 JWT 颁发方
   • 选项 A：共享密钥（所有网关使用相同的 JWT_SECRET_KEY）
   • 选项 B：联合 SSO（Google、GitHub、Entra ID）

3. 启用身份验证：

   AUTH_REQUIRED=true
   UAID_FORWARD_AUTH=true
   

身份验证流程：

跨网关调用会通过 Authorization 标头转发用户的 bearer token。 远程网关通过现有身份验证中间件验证令牌，并保留 RBAC 上下文。

安全功能：

• ✅ 默认拒绝：空的允许列表会阻止所有跨网关路由
• ✅ 转发 bearer token：跨跃点保留用户身份验证
• ✅ 审计跟踪：在标头中跟踪源网关和用户
• ✅ 清晰的错误消息：在启动和运行时捕获配置错误

故障排查：

• “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 多个环境变量的完整列表，请参阅 配置参考。

运行

快速参考

开发服务端（Uvicorn）

make dev                 # Uvicorn on :8000 with auto-reload and SQLite
# or
./run.sh --reload --log debug --workers 2

run.sh 是 uvicorn 的封装脚本，可加载 .env、支持重新加载，并将参数传递给服务端。

主要标志：

生产服务端（Gunicorn）

make serve               # Gunicorn on :4444 with multiple workers
make serve-ssl           # Gunicorn behind HTTPS on :4444 (uses ./certs)

Docker Compose（完整技术栈）

make compose-up          # Start full stack: PostgreSQL, Redis, 3 gateway replicas, Nginx on :8080
make compose-sso         # Start SSO stack with Keycloak on :8180
make sso-test-login      # Run SSO smoke checks (providers + login URL + test users)
make compose-logs        # Tail logs from all services
make compose-down        # Stop the stack

手动运行（Uvicorn）

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

云部署

ContextForge 可部署到任何主流云平台：

如需全面的部署指南，请参阅 部署文档。

API 参考

服务端运行时可使用交互式 API 文档：

• Swagger UI — 在浏览器中直接尝试 API 调用
• ReDoc — 浏览完整的端点参考

快速身份验证：

# Read JWT_SECRET_KEY from your .env (it must already contain a real secret)
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)

# Generate a JWT token
export TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  --username [email protected] --exp 10080 --secret "$JWT_SECRET_KEY")

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

如需涵盖所有端点的完整 curl 示例，请参阅 API 使用指南。

测试

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

有关文档测试的详细信息，请参阅 Doctest 覆盖率指南。

项目结构

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 服务。 请始终使用具有受限功能的沙箱、容器或 microVM（例如 gVisor、Firecracker）。 注册任何远程 MCP 服务时都要谨慎，包括来自公共目录的服务——在授予其访问网关的权限前，请自行进行安全评估。

如需查看完整结构，请参阅 CONTRIBUTING.md 或运行 tree -L 2。

开发

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

运行 make 查看所有可用目标。

如需了解开发工作流，请参阅：

• 开发人员工作站设置
• 构建与打包

故障排除

常见问题及解决方法：

如需详细的故障排除指南，请参阅 故障排除文档。

贡献

1. Fork 仓库并创建功能分支。
2. 运行 make lint 并修复所有问题。
3. 确保 make test 全部通过。
4. 使用签名提交打开 PR（git commit -s）。

完整指南请参阅 CONTRIBUTING.md；有关如何提交 Bug、请求功能以及查找可处理的问题，请参阅 Issue Guide #2502。

更新日志

完整更新日志请见：CHANGELOG.md

许可证

根据 Apache License 2.0 许可 — 详见 LICENSE

Star 历史和项目动态