cortex-gateway

Cortex Gateway

N 個のプレーン HTTP バックエンドの前段に置く、仕様準拠で OAuth で保護された単一の MCP サーバーを提供する、フェデレーション型 MCP ゲートウェイです。

業務アプリは通常の Web サービスのままです。それぞれが単一の POST /api/cortex/backend エンドポイント（約 120 行のコントラクトで、MCP ライブラリも stdio も不要）を公開します。ゲートウェイはそれらのツールを検出し、1 つの MCP カタログに統合して、 OAuth 2.1 とスコープを適用し、tools/call を所有するバックエンドにルーティングして、 仮名化された監査証跡を保持します。

これは 1 つの要件を満たすために作られています。会社の誰もが、自分自身の権限だけを与えて、 自分のエージェントにアクセスキーを渡せることです。それ以上でも、それ以下でもありません。 エージェントが自律型アシスタントになっても、答えは変わりません。エージェントはユーザーの ID を借り、アプリはそのユーザーの権限を適用し続けます。ゲートウェイは何も決定しないため、 新たに信頼する必要もありません。

言い換えると、AI エージェントのためのゼロトラスト原則です。ユーザーが誰で何をできるかを 管理する IAM と、エージェントがツールを呼び出す方法を定める MCP エコシステムをつなぐ、 欠けていたリンクです。完全な ZTNA 製品ではなく、エージェント向けの ID・アクセス層です。

バックエンドとは、専用 MCP を本質だけに絞ったものです。つまり、プレーンな HTTP JSON-RPC を 介したツールカタログとツール呼び出し（およびオプションのプロンプト／リソース）です。 トランスポートとライフサイクルの仕組み（initialize、セッション、SSE、バージョンネゴシエーション）は ゲートウェイに集約されています。コントラクトは MCP の意味的なサブセットであるため、 ネイティブ MCP サーバーも組み込みの MCP→バックエンドプロキシアダプターを通じてフェデレーションできます （docs/mcp-adapter.md）。

[MCP agent: Claude Desktop / claude.ai Custom Connector / any MCP client]
         │  HTTPS + OAuth 2.1 JWT (Bearer)
         ▼
[cortex-gateway]  ←— thin gateway, no business logic
         │  HTTPS + the same JWT propagated (RFC 8707)
         ▼
[your backends]   ←— domain owners, plain HTTP, own their ACLs

概要

• 基盤となるアプリの権限が、ユーザーレベルで自動的に適用されます。 ゲートウェイは権限をコピーも 複製もしません。実際のユーザー ID を伝播します（ファーストパーティのバックエンドにはユーザーの JWT を、 プロキシ経由のサードパーティ MCP サーバーにはユーザー自身のリンク済みトークンを渡します）。 そのため、各アプリのネイティブな権限モデルがユーザーごとに適用され、同期もサービスアカウントによる 権限の一律化も不要です。ホスト型ツールアグリゲーターとは異なり、トークン保管庫と監査証跡は 自社のインフラストラクチャ内に保持されます。
• N 個のコネクターではなく、単一の境界を設けます。 各アプリを個別の MCP コネクターとして接続しても ネイティブな権限は維持されますが、同意は N 個、トークン保管庫も N 個となり、共有監査も アプリ間の権限設定もできず、ツール一覧があふれてしまいます。ゲートウェイはユーザーごとのモデルを 損なわずに、それらを単一の OAuth インターフェースに集約します。権限を失わずに統合できます。
• アプリが MCP にロックインされません。 バックエンドは、プレーン HTTP 上の最小限の JSON-RPC コントラクトを使用します。ゲートウェイを取り除いても、直接呼び出せます （テスト、バッチジョブ、その他の連携）。
• 1 つの JWT で N 個のバックエンドに接続できます。 エージェントは一度だけ認証し、ゲートウェイが トークンを伝播します。各バックエンドがトークンを再検証し、それぞれの権限を適用します。 認可サーバーで失効させれば、すべてのアクセスが遮断されます。
• 障害を分離できます。 到達できないバックエンドは tools/list から消えるだけで、ほかの バックエンドは引き続き動作します。
• コンテキストを考慮したフェデレーション。 バックエンドのフィルタリングとコンパクトな「検索」 モードにより、ツールカタログがエージェントのコンテキストを埋め尽くすのを防ぎます （docs/tool-search-mode.md）。
• エージェントのフィードバックループ。 ツールが見つからない、または機能が不十分な場合、 エージェントは report_missing_capability チケットを登録できます。チケットは重複排除と トリアージが行われ、ブロッキング時には任意で Webhook に送信されます。

ユースケース

全社規模のエージェント向けインターフェース。 組織が N 個の社内アプリ（CRM、品質文書、請求、分析など）を運用しています。各アプリに約 120 行のバックエンドエンドポイントを追加すると、ゲートウェイがそれらを会社の SSO で保護された 1 つの MCP コネクターとして公開します。従業員は単一の URL を Claude Desktop / claude.ai に設定するだけで、自分のトークンのスコープで許可されたツールだけを利用でき、監査記録も一元管理できます。これは、このゲートウェイが生まれたときの構成です。

プロダクトビルダー。 複数の製品を提供しており、エージェント（自社または顧客のもの）にそれらを操作させたいとします。製品ごとに MCP サーバーを保守する代わりに、各製品でバックエンドコントラクトを実装すれば、ゲートウェイが単一のバージョン管理された OAuth 保護付きエージェント API になります。エージェント向けインターフェースへの製品追加は、環境変数を 1 つ設定するだけです。

テーマ別ハブ／厳選レジストリ。 ゲートウェイを トピック エンドポイントとして運用します。たとえば、「ドメイン X のすべてのオープンデータツール」を、1 つの URL と 1 つのトークンの背後で複数のプロバイダーにフェデレーションします。スコープモデルによりプロバイダーごとにオプトインでき、get_help／get_snapshot によってエージェントが自己記述型の情報を使って探索でき、監査記録から実際の利用状況を把握できます。プロバイダーは（意図的に小規模な）バックエンドコントラクトをネイティブに実装するか、市販の MCP サーバーの場合は、組み込みの MCP→バックエンドプロキシアダプターを前段に配置します（docs/mcp-adapter.md）。

無料／有料のツール階層。 スコープは利用権限です。認可サーバーで無料ユーザーには mcp:yourapp:basic、有料ユーザーには mcp:yourapp:pro を付与し（請求ウェブフックで付与内容を更新します）、ゲートウェイが各呼び出し元にプランで利用できるツールだけを表示し、許可するようにできます。ゲートウェイにもバックエンドにもペイウォールのロジックは不要で、ツールがスコープを宣言するだけです。取り消しやダウングレードは通常の OAuth チェーンを通じて反映されます。

ネイティブ MCP サーバーのフェデレーション（アダプター、ベータ版）

組み込みの MCP→バックエンドプロキシアダプター を使うと、コントラクトバックエンドと、市販のネイティブ MCP サーバー（Canva、Figma など）を 1 つのバンドルに混在させられます。アダプターは下流側では MCP クライアント（initialize、セッション、SSE フレーミング）として、上流側では通常のバックエンドとして動作するため、ゲートウェイのコアに変更は不要です。ユーザーごとの下流 OAuth は、トークン保管庫（保存時に AES-256-GCM を使用）と連携フロー（RFC 9728 ディスカバリー、Dynamic Client Registration、PKCE）で処理されます。各ユーザーはプロバイダーごとに一度同意すれば、その後は単一の Cortex トークンでバンドル全体のエージェントが識別されます。実例の「デザインバンドル」（Canva + Figma + 独自のバックエンド）については、docs/mcp-adapter.md をご覧ください。

ロードマップ

• バックエンドごとのオーディエンス — 呼び出し元のトークンを、対象バックエンドをオーディエンスとするトークンに交換します（RFC 8693）。これにより、バックエンドが受け取ったトークンをゲートウェイに対して再利用できなくなります（docs/security.md §6）。
• ツールのアノテーションと出所情報 — バックエンドコントラクトの readOnlyHint／destructiveHint を tools/list に引き継ぎ、結果にその出所を付記し、書き込みを確認します。
• 2026-07-28 の完全対応 — ステートレスクライアント向けに、リスト変更通知を行う subscriptions/listen を追加します。バックエンドは引き続きバックエンドコントラクト経由で呼び出されるため、クライアントのプロトコル世代の影響を受けません。
• ディスカバリー向けマシン ID — AS が対応したら、静的な技術トークンを client_credentials フローに置き換えます。
• 共有イベントバス／レート制限ストア — 複数インスタンスのデプロイ向けです。

特徴

• 同一エンドポイントで MCP spec 2026-07-28（ステートレス：server/discover、セッションなし、Mcp-Method／Mcp-Name ヘッダーを本文と照合して検証、キャッシュヒント）と 2025-11-25 / 2025-06-18（Streamable HTTP：initialize、listChanged 通知用 GET SSE、セッション終了用 DELETE）に対応し、リクエストごとに選択されます
• プリミティブ：ツール、リソース（URI テンプレートを含む）、プロンプト
• OAuth 2.1 リソースサーバー：JWKS 検証、リソースごとのオーディエンス（RFC 8707）、保護リソースメタデータ（RFC 9728）、失効確認のための RFC 7662 イントロスペクション（オプション）
• スコープベースの可視性：エージェントに表示され、呼び出せるのは、トークンのスコープで許可されたツールのみです。ディスカバリーの scopes_supported は、フェデレーションカタログから動的に導出されます
• 動的ディスカバリー：バックエンドを60秒ごとにポーリングします。ゲートウェイを再デプロイしなくても新しいツールが表示され、SSE tools/list_changed でプッシュ通知されます
• 組み込み機能：whoami（バックエンドをまたいだ集約 ID）、find_tools、report_missing_capability、list_cortex_tickets、list_cortex_resources、read_cortex_resourceに加え、実行時に生成される自己記述型の cortex://architecture リソース
• 監査証跡：呼び出しごとに stdout に1行の JSON を出力（メールアドレスとパラメーターをハッシュ化）。PostgreSQL への保存と保持期間クーロンはオプションです
• Origin 許可リスト（DNS リバインディング対策）、トークンごとのレート制限、プールサンドボックス（オプション）
• CI で実際の OAuth 経路を通じて 公式 MCP 適合性テストスイートで検証済みです。32件のサーバーシナリオのうち22件に合格しています。残りの10件は、ゲートウェイが宣言していないオプション機能（補完、ロギング、サブスクリプション、進捗、サンプリング、エリシテーション）をテストします。理由は scripts/conformance/baseline.yml に記載されています

クイックスタート（OAuth サーバー不要）

git clone https://github.com/wellknownmcp/cortex-gateway
cd cortex-gateway
npm install

# 1. Start the demo backend (dependency-free)
node examples/demo-backend/server.mjs &

# 2. Configure the gateway
cat > .env.local <<'EOF'
OAUTH_ISSUER=https://auth.example.com
CORTEX_BACKENDS=demo
CORTEX_BACKEND_DEMO_URL=http://127.0.0.1:4820
CORTEX_TECHNICAL_TOKEN=demo-technical-token
CORTEX_DEV_BYPASS_TOKEN=dev-secret
CORTEX_DEV_BYPASS_SCOPES=mcp:demo:read
EOF

# 3. Run it
npm run dev

# 4. Talk MCP (dev bypass replaces the Bearer JWT locally)
curl -s http://localhost:3213/mcp \
  -H 'Content-Type: application/json' \
  -H 'X-Dev-Mode: dev-secret' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'
# → whoami, ..., demo_get_help, demo_echo, demo_get_time

curl -s http://localhost:3213/mcp \
  -H 'Content-Type: application/json' \
  -H 'X-Dev-Mode: dev-secret' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"demo_echo","arguments":{"message":"hello"}}}' | jq

本番環境では、OAUTH_ISSUER を OAuth 2.1 認可サーバー（JWKS エンドポイントを備え、scope クレームをサポートする RS256 JWT を発行するサーバーならどれでも可）に設定し、MCP クライアントから、aud がゲートウェイの正規 URI である Bearer トークンを使って https://your-host/mcp に接続します。

stdio ブリッジ（stdio 専用クライアントおよびディレクトリのサンドボックス向け）

ゲートウェイはリモートの Streamable HTTP サーバーですが、一部の MCP クライアントや、Glama のようなディレクトリの Docker 検査ハーネスは stdio トランスポートにしか対応していません。scripts/stdio-bridge.mjs は両者を橋渡しします。実際の JWT 検証経路をバイパスせずに、一時的なローカル OAuth 発行者に対して本番ビルドを起動し、自身に短期間有効なトークンを発行して、stdin/stdout と POST /mcp の間で改行区切り JSON-RPC を中継します。

npm run build
npm run start:stdio   # stdio MCP server on stdin/stdout

自己付与するスコープは BRIDGE_SCOPES で指定します（ゲートウェイの組み込み機能には不要です）。ゲートウェイのポートは BRIDGE_GATEWAY_PORT で指定します（デフォルトは3213）。設計メモと注意点（stdout の純粋性、プロトコルバージョンのネゴシエーション、セッションのエコー）： https://cortex-gateway.dev/guides/expose-http-mcp-server-over-stdio/.

バックエンドの追加

1. アプリにコントラクトを実装します — POST エンドポイントを1つ、list_tools とツールを提供します（docs/backend-contract.md、リファレンス実装は examples/demo-backend/ にあります）。
2. 宣言します：

   CORTEX_BACKENDS=demo,docs
   CORTEX_BACKEND_DOCS_URL=http://127.0.0.1:4001
   

3. 完了です。ゲートウェイは60秒以内に docs_* ツールを検出し、接続中のクライアントに tools/list_changed をプッシュ通知します。

設定

すべて環境変数で制御します。注釈付きの全一覧は .env.example を参照してください。主な項目は次のとおりです。

変数	必須	用途
CORTEX_CANONICAL_URI	本番環境	正規の MCP リソース URI（RFC 9728）、デフォルトの JWT audience
OAUTH_ISSUER	はい	お使いの OAuth 2.1 認可サーバー
CORTEX_BACKENDS + CORTEX_BACKEND_<ID>_URL	はい	フェデレーションされたバックエンド
CORTEX_TECHNICAL_TOKEN	はい	カタログ検出用の静的トークン（カタログメソッドのみ）
CORTEX_ALLOWED_ORIGINS	本番環境	許可する Web オリジン（完全一致または *.suffix）
CORTEX_TOOL_INTEGRITY_MODE	いいえ	warn（デフォルト）または block — ツール定義のラグプル検出
CORTEX_ADMIN_SECRET	block の場合	/api/admin/tool-integrity 用のシークレット。隔離を確認して解除する運用者向けエンドポイントです
CORTEX_TOOL_BASELINE_FILE	block の場合	承認済みツール定義の永続化先。設定しない場合、再起動時に現在の状態が再承認されます
CORTEX_BASELINE_PRIVATE_KEY / _PUBLIC_KEY	いいえ	このストアへの Ed25519 署名。公開鍵のみの場合、ゲートウェイは承認を検証できますが、承認を発行できません
OAUTH_REQUIRED_SCOPES	いいえ	ディスパッチ前に要求する基本スコープ
CORTEX_DATABASE_URL	いいえ	監査ログの永続化とゲートウェイチケット用の PostgreSQL
CORTEX_TICKET_WEBHOOK_URL	いいえ	機能不足チケットをブロックするための Webhook
CORTEX_BACKEND_<ID>_SCOPE_PREFIXES	いいえ	バックエンドが宣言できるスコープのプレフィックス（デフォルトは mcp:<id>:） — docs/security.md §7
CORTEX_BACKEND_<ID>_URI_SCHEMES	いいえ	バックエンドがリソースに対して要求できる URI スキーム（デフォルトは <id>）
CORTEX_TRUSTED_PROXY_HOPS	プロキシ経由の場合	X-Forwarded-For の読み取りに使用する、前段の信頼済みプロキシ数（デフォルトの 0 は無視）
CORTEX_WEBSITE_URL	いいえ	MCP クライアントに表示する websiteUrl（デフォルト：ゲートウェイのオリジン）。サーバーアイコン：public/icon-{light,dark}.png を置き換えてください

セキュリティモデル

2 つの経路があり、その違いこそが設計の要です。カタログは、一覧表示しかできないテクニカルトークンを使ってバックグラウンドで検出され、呼び出しではユーザー自身のトークンがバックエンドまでそのまま渡されます。

sequenceDiagram
    autonumber
    participant Agent as AI agent
    participant GW as Cortex Gateway
    participant AS as Authorization server
    participant App as Backend app

    rect rgba(128,128,128,0.10)
    note over GW,App: Catalog refresh — every 60s, no user involved
    GW->>App: tools/list (CORTEX_TECHNICAL_TOKEN)
    App-->>GW: full tool catalog
    note over GW: Fingerprint each definition<br/>(rug-pull detection)
    end

    note over GW,AS: JWKS fetched once and cached —<br/>tokens are verified locally, not per call

    Agent->>GW: tools/list (user JWT)
    note over GW: Verify signature, issuer, audience<br/>Filter the cached catalog by the token's scopes
    GW-->>Agent: only the tools this user may call

    Agent->>GW: tools/call demo_echo (user JWT)
    note over GW: Check the scope declared by that tool
    GW->>App: tools/call — the user's JWT, forwarded
    note over App: Applies its own roles and ACLs<br/>to that user
    App-->>GW: result, under the user's own rights
    GW-->>Agent: result
    note over GW: One audit line: who, which tool,<br/>which backend, which scope

エージェントがユーザーの持っていない認証情報を保持することはなく、経路上のどこにも過剰な権限を持つサービスアカウントは存在しません。

エージェントのアクセスは、ゲートウェイのポリシーではなく、設計によって安全性が確保されています。以下は、AI アプリに組み込む MCP ツールに求めるべき特性です。

• 共有 API キーではなく OAuth 2.1 — すべての呼び出し元がそれぞれのユーザーとして認証されます。トークンはユーザーごとに発行され、スコープが設定され、失効可能です。
• 権限の平坦化なし — 実際のユーザーの ID が各バックエンドに伝播されるため、過剰な権限を持つサービスアカウントは存在せず、エージェントにはユーザー自身の権限だけが与えられます。
• 最小権限 — 呼び出し元ごとにスコープでフィルタリングされたツールカタログが使われ、エージェントにはトークンで許可されたツールだけが表示されます。
• 検証可能 — OAuth のディスカバリーチェーン全体をトークンなしでたどれるため、接続前にセキュリティ状況を確認できます（自分で、またはサードパーティのスキャナーを使って確認できます）。

内部では、次のように動作します。

• ゲートウェイはビジネス権限について何も決定しません。OAuth スコープが入口となり（ゲートウェイとバックエンドの 2 回確認）、アプリケーションロールと ACL は各バックエンドに存在します。

• 静的なテクニカルトークンでアクセスできるのはカタログメソッドのみです（src/contract/static-token.ts）。すべてのデータメソッドでは、エンドユーザーの JWT が必要です。

• 監査ログは設計上、仮名化されます（メールアドレスのハッシュ化、パラメーターのハッシュ化）。仮名化は匿名化ではありません。ハッシュ化された識別子も GDPR 第 4 条 5 項に基づく個人データであるため、監査証跡は処理記録に含め、保持期間を定める必要があります。

• セッションはトークンの sub に紐付けられます。他者のセッション ID には 404 が返されます。 フェデレーションゲートウェイは、単一のサーバーでは実施できない制御を実施できます。 すべてのバックエンドのツール定義と、バックエンドへのあらゆる呼び出しを把握しているため、ゲートウェイはエコシステムのインシデント報告で繰り返し見つかっている問題を検出するのに適した場所です。詳細はすべてdocs/security.mdをご覧ください。

• ラグプルの検出。 ツール定義は初回確認時にフィンガープリント（description、inputSchema、scope、version）が作成され、更新のたびに再確認されます。名前を変えずにツールの説明内容を書き換えたバックエンドは報告されます。また、CORTEX_TOOL_INTEGRITY_MODE=block の場合、そのツールはオペレーターが /api/admin/tool-integrity で確認するまで隔離されます。これは HTTP エンドポイントであり、MCP ツールではないため、モデルが独自にラグプルを解除することはできません。ほとんどの実装で行われる名前レベルの変更検出では、まさにこの攻撃を見逃します。

• リモートホストへの平文送信を防止。 すべてのフェデレーション呼び出しで呼び出し元のトークンが転送されるため、ループバック以外を指す http:// バックエンド URL は読み込み時に拒否されます。サードパーティーサーバーのメタデータからアダプターが検出する OAuth エンドポイントにも同じ検証が適用されます。これは CVE-2025-6514 の原因となった種類のバグです。

• 追跡可能な監査。 各行には、どのバックエンドが呼び出しを処理したか、その際のスコープも記録されます。ツール名だけではありません。

• バックエンドが許可された範囲を逸脱しないようにします。 バックエンドが宣言できるスコープは自身のプレフィックス配下に限られ、自身の URI スキームのみを申告できます。プロンプトにはツールと同様にプレフィックスが付加されます。リソースの読み取りは、一覧表示時のフィルタリングだけでなく、URI が該当するテンプレートのスコープに照らして検証されます。

適用範囲について正直に説明します。承認内容は再起動後も保持され（CORTEX_TOOL_BASELINE_FILE）、オペレーターが署名することもできます。そのため証明できるのは「ここで承認してから定義が変更されたこと」であり、「ベンダーが公開した定義と同一であること」ではありません。

トークン転送について明確に説明します。 呼び出し元のトークンは呼び出しを処理するバックエンドに転送され、そのオーディエンスはゲートウェイです。これによってサービスアカウントが不要になります。その一方で、フェデレーションされたバックエンドは受け取るトークンの信頼境界内にあります。侵害されたバックエンドは、ゲートウェイに対してトークンをリプレイできる可能性があります。ゲートウェイはトークンを受け取る対象を制限します（処理を担当するバックエンドのみ、呼び出し元がスコープを持つバックエンドのみ、平文では決して転送しません）。トークン交換によるバックエンドごとのオーディエンス設定はロードマップにあります。詳細と推奨事項については、docs/security.md §6をご覧ください。

コンプライアンス。 これらは、監査で自動アクセスについて検証される制御です。最小権限のスコープ、ユーザーごとの ID（過剰な権限を持つサービスアカウントは使用しません）、呼び出しごとに追跡可能な監査証跡、集中管理された失効機能です。これらは ISO 27001:2022 Annex A のアクセス制御およびログ記録に関する制御（A.5.15、A.5.16、A.5.17、A.5.18、A.8.2、A.8.15、A.8.16）と SOC 2 の CC6／CC7 に対応しており、どちらも現在適用されます。よく引用される EU AI Act の条項（Art. 12 の記録保持、Art. 14 の人間による監督）は、高リスクの AI システムのみに適用されます。また、2026 年の Digital Omnibus により、これらの義務は 2027 年 12 月 2 日（独立した Annex III）および 2028 年 8 月 2 日（組み込み型 Annex I）まで延期されました。社内でのエージェント導入のほとんどは高リスクではなく、ゲートウェイはアクセスインフラであり、AI システムではありません。セルフホスト可能なため、監査証跡とトークン保管庫は自社の境界内にとどまり、GDPR Art. 28 に基づく追加の副処理者も、SOC 2 の対象範囲に加わるものもありません。Cortex が提供するのは制御機能であり、認証ではありません。対応関係の全一覧は次をご覧ください。 https://cortex-gateway.dev/answers/ai-agent-compliance-controls/

開発

npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run build       # prisma generate + next build

どの環境でもデータベースは任意です。CORTEX_DATABASE_URL が設定されていない場合、監査ログは標準出力に記録され、ゲートウェイローカルのチケットは無効になります。

ライセンス

MIT