MCP Gateway

ContextForge

MCP、A2A、REST/gRPC API を連携させ、一元的なガバナンス、検出、可観測性を実現するオープンソースのレジストリ兼プロキシです。エージェントとツールの呼び出しを最適化し、プラグインをサポートします。

ContextForge は、ツール、エージェント、API を連携させ、AI クライアント向けの使いやすい単一のエンドポイントに集約するオープンソースのレジストリ兼プロキシです。AI インフラストラクチャ全体にわたる一元的なガバナンス、検出、可観測性を提供します。

• ツールゲートウェイ — MCP、REST、gRPC から MCP への変換、TOON 圧縮
• エージェントゲートウェイ — A2A プロトコル、OpenAI 互換および Anthropic エージェントのルーティング
• 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 を統合するオープンソースのレジストリ兼プロキシであり、一元的なガバナンス、検出、可観測性を提供します。エージェントとツールの呼び出しを最適化し、プラグインにも対応しています。詳しくはプロジェクトのロードマップをご覧ください。

現在、次の機能に対応しています。

• 複数の MCP サービスおよび REST サービス間のフェデレーション
• 外部 AI エージェント（OpenAI、Anthropic、カスタム）との A2A（Agent-to-Agent）統合
• リフレクションに基づくサービス検出の自動化による gRPC から MCP への変換
• レガシー API の MCP 準拠ツールおよびサーバーとしての仮想化
• HTTP、JSON-RPC、WebSocket、SSE（キープアライブの設定可能）、Streamable HTTP によるトランスポート。サーバー側での利用には stdio トランスポートも利用可能
• リアルタイムの管理、設定、ログ監視が可能な管理 UI（エアギャップ環境へのデプロイにも対応）
• 別のコンテナーで動作する、再設計された使いやすいWeb UI
• ユーザー単位の OAuth トークンと、無条件での X-Upstream-Authorization ヘッダー対応を備えた、組み込みの認証、リトライ、レート制限
• Phoenix、Jaeger、Zipkin、その他の OTLP バックエンドに対応した OpenTelemetry による可観測性
• 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 または依存関係の解決エラーが発生した場合は、これが原因です。代わりにイメージを pull してください（以下の手順 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 では、デフォルトの fast-time サービスを維持するために、両方のコマンドで PROFILE="--profile with-fast-time --profile ui" を使用してください。

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（rootless に適しています）

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 Dev Container

リポジトリをクローンして 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 クレートは 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 ヘッダー経由で転送されます。 リモートゲートウェイは既存の認証ミドルウェアを通じてトークンを検証し、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 以上の環境変数の一覧については、**設定リファレンス**を参照してください。

実行

クイックリファレンス

開発サーバー（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 サーバーをローカルファイルシステム上で直接実行しないでください。 gVisor や Firecracker などを使用し、機能を制限したサンドボックス、コンテナ、またはマイクロ VM で 必ず実行してください。公開カタログのサーバーを含むリモート 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. リポジトリをフォークし、機能ブランチを作成します。
2. make lintを実行し、問題があれば修正します。
3. make testが成功する状態を維持します。
4. 署名付きコミット（git commit -s）を含む PR を作成します。

詳しいガイドラインは**CONTRIBUTING.mdを、バグの報告、機能のリクエスト、取り組む課題の探し方についてはIssue Guide #2502**を参照してください。

変更履歴

変更履歴の全容はこちらにあります：CHANGELOG.md

ライセンス

Apache License 2.0のもとでライセンスされています。詳細はLICENSEを参照してください。

スター履歴とプロジェクトの活動状況