MCP Gateway

軽量でセルフホスト型のMCPアグリゲータゲートウェイ — 何台でも配置できる保護されたバックエンドMCPサーバーの前面に、1つの公開MCPエンドポイントを提供します。さらに、MCP クライアント側に OAuth 2.1 に準拠した認可サーバー を備えており、既存のゲートウェイの大部分に欠けている部分を補完します。

Claude Code / Claude.ai ──OAuth 2.1 (DCR/CIMD + PKCE)──▶ MCP Gateway ──own credentials──▶ GitHub MCP
                                                          │                              ▶ Microsoft Learn MCP
                                                          └── /mcp (Streamable HTTP)      ▶ …more backends

FastAPI + FastMCP で構築され、単一の YAML ファイルで設定します。状態は暗号化された単一の SQLite データベースに保存され、小さなスタンドアロンコンテナ 1つとして配布されるため、リバースプロキシは不要です（TLS を利用したい場合は前段に配置することもできます）。

機能

クライアント側 (MCP 認可仕様、2025-11-25):

• 必須の PKCE（S256) を伴う OAuth 2.1 認可コードフロー

• /register における 動的クライアント登録（RFC 7591）— 事前共有の資格情報なしで claude mcp add が動作します

• クライアント ID メタデータドキュメント (CIMD) — HTTPS URL をクライアント ID として使用し、private_key_jwt クライアント認証にも対応。client_id_metadata_document_supported: true によってサポートを告知します

• 認可サーバー メタデータ（RFC 8414）+ OIDC ディスカバリのエイリアス

• 保護リソースメタデータ（RFC 9728）。Claude のコネクタが要求する 401 レスポンスに WWW-Authenticate: Bearer resource_metadata="…" を含めます

• リソースインジケータ（RFC 8707）を受け入れ、発行済みトークンに紐付けます

• 有効期間の短い不透明アクセストークン、ローテーションするリフレッシュトークン、使い捨ての認可コード — すべて ハッシュ化 して保存し、クライアント レコードは保存時に暗号化します

• ループバック リダイレクト URI は ポート非依存 で照合します（Claude Code CLI はあるポートで登録し、別のポートで認可するため）。ループバック以外の URI は完全一致登録が必要です

• 小さな Svelte 5 によるログイン＋同意UI（設定ファイルに記載した単一のローカル ID）

バックエンド側:

• none — 公開サーバー用（例: Microsoft Cloud Learn MCP）

• bearer — 静的トークンの挿入（Authorization: Bearer …、例: PAT）

• headers — 任意の静的ヘッダー（API キーなど）

• oauth — MCP 仕様に従った完全な OAuth クライアント：メタデータ検出、アップストリームの AS が対応する場合の CIMD（ゲートウェイが自身のクライアント メタデータ ドキュメントをホスト）、DCR フォールバック、PKCE、自動トークン リフレッシュ。ブラウザ経由で一度接続すれば、トークンは Fernet 暗号化で SQLite に永続化されます

• クライアントのゲートウェイ トークンがアップストリームに転送されることはありません（仕様が要求するトークン パススルーなし）。バックエンドが参照できるのは、ゲートウェイが保持する資格情報だけです

集約:

• ツール/リソース/プロンプトをバックエンドごとに名前空間化: github_create_issue、msdocs_microsoft_docs_search`、…

• Streamable HTTP によるライブプロキシ。ダウン中または未接続のバックエンドは、ゲートウェイ全体を壊すのではなく、自身のツールだけを除外します

• 組み込みの gateway_status ツール

Related MCP server: MCP OAuth Test

クイックスタート

cp config.example.yaml config.yaml
$EDITOR config.yaml                                   # set public_url, users, backends
cp .env.example .env
$EDITOR .env                                           # set MCP_GATEWAY_ENCRYPTION_KEY (openssl rand -base64 32)
docker compose up -d

ゲートウェイはスタンドアロンで動作し、商:8000 をリッスンします。docker compose は .env から MCP_GATEWAY_ENCRYPTION_KEY を自動的に読み取ります。TLS を利用する場合はお好みのリバースプロキシの後ろに置くか、ポートを直接公開してください。

設定ファイル用のパスワードハッシュを生成します:

docker compose run --rm mcp-gateway mcp-gateway hash-password

Claude Code（CLI）を接続する

claude mcp add --transport http gateway https://mcp.example.com/mcp

Claude Code はゲートウェイの認可サーバーを検出し、DCR 経由で自己登録（または自身の CIMD クライアント ID を使用）した上でブラウザを開きます。config.yaml のユーザーでログインして承認すれば完了です。トークンを貼り付ける必要はありません。

Claude.ai / Claude Code web を接続する（カスタムコネクタ）

カスタムコネクタとして https://mcp.example.com/mcp を追加します。https://claude.ai/api/mcp/auth_callback へのブラウザ リダイレクトも、同じログイン/同意フローを通過します。

OAuth バックエンドを接続する

https://mcp.example.com/ui/backends を開いてサインインし、各 OAuth バックエンド（例: GitHub MCP）の横にある Connect を押します。バックエンドの認可サーバーへは一度だけリダイレクトされ、その後はゲートウェイが自動的にトークンを更新します。

設定

すべての設定は単一の YAML ファイル（config.example.yaml を参照）に集約されます。値は ${ENV_VAR} / ${ENV_VAR:-default} 展開をサポートします。

server:
  public_url: https://mcp.example.com   # behind your reverse proxy

auth:
  encryption_key: ${MCP_GATEWAY_ENCRYPTION_KEY}   # encrypts secrets at rest
  users:
    - username: admin
      password_hash: "$2b$12$…"          # mcp-gateway hash-password
  access_token_expiry_seconds: 3600
  refresh_token_expiry_seconds: 2592000

storage:
  path: /data/gateway.db                 # SQLite; the only state

backends:
  github:                                # → tools namespaced github_*
    url: https://api.githubcopilot.com/mcp/
    auth:
      type: oauth
      # GitHub's authorization server supports neither CIMD nor DCR, so
      # register a GitHub OAuth App and provide its credentials directly:
      client_id: ${GITHUB_OAUTH_CLIENT_ID}
      client_secret: ${GITHUB_OAUTH_CLIENT_SECRET}
  microsoft-docs:                        # → tools namespaced microsoft-docs_*
    url: https://learn.microsoft.com/api/mcp
    auth: { type: none }
  something-with-a-pat:
    url: https://example.com/mcp
    auth: { type: bearer, token: "${SOME_PAT}" }

バックエンドの追加は設定変更だけで完了します — コード変更は不要です。

バックエンド認証リファレンス

oauth バックエンドの場合、ゲートウェイは <public_url>/oauth/client-metadata.json に自身のクライアント ID メタデータ ドキュメントをホストし、アップストリームの AS が CIMD サポートを告知している場合は常にそれをクライアント ID として使用します（HTTPS の public_url が必要です）。それ以外の場合は Dynamic Client Registration にフォールバックします。アップストリームの AS がどちらもサポートしていない場合（例: GitHub）、代わりに事前登録済みの OAuth クライアントを使用するため client_id（機密クライアントの場合は client_secret も）を設定してください — CIMD/DCR は完全にスキップされます。

ロギング

ゲートウェイは stdout/stderr にログを出力します（docker logs、docker compose logs -f）。デフォルトは INFO レベルで、起動/停止、設定の要約、ログイン試行、OAuth の authorize/consent/token 発行、アップストリーム バックエンドの接続/切断、バックエンドのマウント状態を記録します。DEBUG ではより詳細な情報（クライアント構築、トークンローテーション、CIMD 更新、ストレージの整理）が追加されます。認証情報やトークンがログに記録されることは、どのレベルでもありません。

レベルは MCP_GATEWAY_LOG_LEVEL 環境変数（debug、info、warning、error、critical）で設定します:

# .env (picked up by docker compose)
MCP_GATEWAY_LOG_LEVEL=debug

# or inline
docker compose run --rm -e MCP_GATEWAY_LOG_LEVEL=debug mcp-gateway

docker-compose.yml はこの変数をコンテナにすでに転送しており、未設定時は info が使われます。

Docker 以外では、mcp-gateway run の --log-level も同様に動作し、環境変数より優先されます:

mcp-gateway run -c config.yaml --log-level debug

エンドポイント

セキュリティ上の注意

• PKCE（S256）が必須です。認可コードは一度きりで、5分で失効します。

• リフレッシュトークンは使用のたびにローテートします（OAuth 2.1 の public client 要件）。

• アクセストークン、リフレッシュトークン、認可コードは SHA-256 ハッシュとしてのみ保存されます。

• 登録済みクライアント レコードと上流の認証情報は、保存時に Fernet で暗号化されます（auth.encryption_key。パスフレーズは scrypt と DB ごとのソルトで引き延ばされます）。

• 子同意画面にはクライアント名と正確なリダイレクト先を表示し、ループバック リダイレクトについては警告します（仕様の CIMD localhost なりすましガイダンス）。

• MCP クライアントへ発行されたトークンがバックエンドへ転送されることはなく、バックエンドの認証情報が MCP クライアントに届くこともありません。

• セッションは署名付き（itsdangerous）、HttpOnly、SameSite=Lax、HTTPS では Secure です。

• 認証情報がログに記録されることはありません。

開発

uv venv && uv pip install -e ".[dev]"     # or: pip install -e ".[dev]"
(cd ui && npm install && npm run build)   # build the Svelte UI
pytest                                    # 35 tests incl. full e2e OAuth flows
mcp-gateway run -c config.yaml

テストスイートは、実際のゲートウェイ（および OAuth で保護されたアップストリームとして動作する 2 つ目のインスタンス）を起動し、HTTP 経由で DCR/CIMD ＋ PKCE の完全なフローを駆動します。

アーキテクチャ

• src/mcp_gateway/oauth_server.py — MCP クライアント向けの認可 AS。プロトコルコードを手書きせず、MCP SDK の認可サーバー ハンドラーと FastMCP の CIMD マネージャーを基盤にしています。ゲートウェイ側では、SQLite 永続化、ログイン/同意の一連のフロー、トークン発行/ローテーションのポリシーを追加します。

• src/mcp_gateway/upstream.py — バックエンド クライアント。OAuth バックエンドでは、公式 SDK の OAuthClientProvider（検出、CIMD/DCR、更新）を、暗号化 SQLite のトークンストアとブラウザ駆動の接続フローと組み合わせて使用します。

• src/mcp_gateway/gateway.py — FastMCP サーバー。各バックエンドは、その名前空間の下にライブプロキシとしてマウントされます。

• src/mcp_gateway/app.py および web.py — FastAPI アプリ: UI 用 JSON API、アップストリームのコールバック、CIMD ドキュメント、静的 Svelte アプリを提供し、FastMCP アプリ（MCP エンドポイント＋ OAuth ルート ＋ WELL-KNOWN）をルートにマウントします。

• ui/ — Svelte 5 ＋ Vite の SPA（ログイン、同意、バックエンド）。

設計上シングルインスタンスです（SQLite ＋ インメモリの接続フロー）。スタンドアロンで動作し、TLS 終端が必要ならご自身のリバースプロキシの後ろに配置し、1ファイルのバックアップだけを取れば済みます。