MCP Gateway — フェーズ 1（KLIP、読み取り専用）

認可されたEnergi-Upスタッフが、アプリケーションを開かずにClaudeを通じて自然言語でKLIPに問い合わせできるようにする、単一のセキュアなサービス。厳密に読み取り専用。

デプロイ先（PRD Q3、現在はクローズ済み）: <gateway-hostname> -> <gateway-public-ip> （ECS-MCP、ap-southeast-5）。ホスト名はmcp-gwであり、v0.9ドキュメントが想定していたmcp.example.comではないことに注意。PRD/TSDはこれに合わせて更新すべきである。

ドキュメント: PRD v0.9 · TSD v0.9 · 実装ガイド · 設計レビュー · デプロイランブック

1. 固定バージョン（T-1）

MCP仕様リビジョンとSDKバージョンはここで固定する。SDK自身のドキュメントが設計ドキュメントと矛盾する場合、SDKが優先される — SDKが正確なAPIを定義するからである。

Related MCP server: Snowflake MCP Server

2. レイアウト

src/
  core/       config, logger, db, audit, cache, rateLimit, semaphore, migrate, errors
  adapters/klip/  routes(APPENDIX A) · fields(APPENDIX A) · client(guard) · session · paginate · normalize
  tools/klip/ 9 tool definitions + shared parameter plumbing
  mcp/        server, envelope, runner
  auth/       keys, hub(OIDC RP), users, clients, tokens, provider, loginPage
  http/       app, consent(Hub + break-glass), health, origin, clientIp
migrations/   idempotent SQL (001 schema, 002 Hub OIDC)
deploy/       nginx config, backup sidecar
test/         120 tests + mock KLIP and mock Hub fixtures

レイヤリングルール（T-3）: tools → adapters → core。エントリポイント以外でhttp/をインポートするものはない。すべてのビジネス正規化はadapters/klip/normalize.tsにあり、これは何もインポートしないため、単体でユニットテスト可能である。

3. 認証 — 下流Hub OIDC

パイロットユーザーはDownstream Hub（OIDC）でサインインする。ゲートウェイはClaudeが通信する認可サーバーのままであり、Hubはその独自の/authorizeフロー内の1ステップである。

SDKのProxyOAuthServerProviderは意図的に使用しない。プロキシすると、ClaudeにHubトークンが渡され、RFC 8707のオーディエンスバインディングが壊れ、Claudeにklip:readより広いHubスコープが付与され、トークン発行が当社の管理外に移るため、S8キルスイッチがライブセッションを無効化できなくなる。

Claude ──/authorize──▶ gateway ──302──▶ Downstream Hub ──302──▶ /authorize/hub/callback
                          │                                              │
                          │        validate id_token (sig/iss/aud/nonce)  │
                          │        check the pilot ALLOWLIST              │
                          ◀──────────────────────────────────────────────┘
                          └──302 code──▶ Claude ──/token──▶ gateway token (klip:read)

認証は認可ではない。 Hubは誰であるかを証明し、usersテーブルがコネクタを使用できるかどうかを決定する。フェーズ1では共有のKLIPサービスアカウントを1つ使用するため、承認されたすべてのユーザーはMCP_READONLYが読み取れるすべてを読み取れる（レビューH8）— パイロットメンバーシップがデータアクセス制御である。リストにないHubアカウントは403を受け取り、<= 15の上限はuser:addによって強制される。

フローでは2つのPKCE交換が実行される。混同しないこと。Claude自身のcode_challengeはClaude→ゲートウェイ区間を保護し（SDKが処理）、ゲートウェイがサーバー側で保持する別のベリファイアがゲートウェイ→Hub区間を保護する。

どのHubクライアントか？ ゲートウェイ自身のもの — KLIPのものではない

MCP Gateway用に新しいOIDCクライアントを登録すること。KLIPのHub登録を再利用しないこと。KLIPがテスト用DWS Hubにすでに登録されている場合でも同様である。

Hubは2つの信頼境界のうち1つにのみ関与する:

KLIPのクライアントを再利用すると、最初の境界が具体的な形で壊れる。ゲートウェイはIDトークンのaudを自身のHUB_CLIENT_IDに対して検証する。KLIPのクライアントIDを共有すると、KLIPログイン中に発行されたIDトークンがゲートウェイに受け入れられることになり、これは混乱した代理人（confused deputy）の形である。クライアントを分離することで、2つの証明書利用者（relying party）が区別可能になる。また、リダイレクトURI許可リスト、クライアントシークレット、ローテーションスケジュール、Hub SSO監査エントリ、無効化スイッチも独立して維持される — コネクタのHubクライアントをオフにしてもKLIPログインを停止させてはならない。

これにはKLIP側の変更は一切不要である。K1〜K4は影響を受けない。

2つのHubインスタンス、2つの登録

ゲートウェイを各Hubに個別に登録し、対応するKLIPとペアリングする:

ペアリングは起動時に強制される。間違った方向で設定すると、単なる不手際ではなく危険だからである:

• KLIP_ENV=production + テスト用HUB_ISSUER → ゲートウェイは起動を拒否する。 テストHubアカウントを作成できる者は誰でも、実際の商用データに到達できてしまう。

• KLIP_ENV=staging + 本番HUB_ISSUER → 警告して続行する。

hub:checkは検出したペアリングを出力するため、カットオーバーは検証可能である:

pairing:       KLIP staging  <->  Hub testing

DWS Hubが要求するもの（バニラOIDCではない）

Docs/SSO-TARGET-APP-INTEGRATION.mdによる。これらのうち4つはOIDCクライアントライブラリが想定するデフォルトと異なり、3つは完全に失敗する:

したがって、HUB_DISCOVERY_URLは明示的に設定され、HUB_CLIENT_SECRETはオプションであり、HUB_TOKEN_BODYはデフォルトでjsonとなり、unsupported_grant_typeの場合にフォームへのワンショットフォールバックがある（どちらが機能したかをログに記録し、固定できるようにする）。

セットアップ手順

1. リダイレクトURI <PUBLIC_URL>/authorize/hub/callbackでゲートウェイをHubのOIDCクライアントとして登録する。これはパブリッククライアントである — シークレットを要求しないこと。

2. HUB_ISSUER、HUB_DISCOVERY_URL、HUB_CLIENT_IDを/opt/mcp/.envに配置する。

3. パイロットユーザーが試す前に検証する:

   docker compose exec -T gateway node dist/cli.js hub:check

   これにより、登録するリダイレクトURIが出力され、ディスカバリが実行され、HubがS256 PKCEを宣伝していない場合に警告する。ゲートウェイは起動時にもディスカバリをプローブし、/healthzでhub_oidcとして報告する。

4. パイロットユーザーを追加する（パスワードなし — Hubが認証する）:

   docker compose exec -T gateway node dist/cli.js user:add someone@example.com "Their Name"

非常用（ブレークグラス）アカウント

Hubがダウンしているか誤設定されている場合に使用するため、ローカルパスワードアカウントは正確に1つだけ許可される:

docker compose exec -T gateway node dist/cli.js user:add-break-glass it-emergency@example.com

これはログインページの開示の背後に隠されており、初回使用時にパスワード変更を強制し、それを通じたすべてのサインインは高重大度でbreak_glass: trueとして監査される。Hub認証ユーザーはパスワードパスをまったく使用できないため、Hubをオフにしても、誰も設定していないパスワードにフォールバックする方法にはならない。

Hub パスが本番で実証されたら、BREAK_GLASS_ENABLED=false に設定して、パスワードの攻撃面を完全に削除してください。

オプションのグループゲート — DWS Hub では利用不可

HUB_REQUIRED_GROUP は、groups クレームに対する2番目のチェックを追加します。DWS Hub は groups クレームを発行しません（openid profile email のみをアドバタイズします）。そのため、これを設定するとすべてのユーザーを拒否することになります。設定した場合、hub:check が警告します。users テーブルのパイロット許可リストが、引き続き認可の制御となります。

IdP 開始ログイン

Hub はダッシュボードのタイルからユーザーをコールバックに直接送り込むことができます。これはコネクタでは機能しません。コールバックは Claude が開始した認可リクエストを完了させるために存在するため、リクエストなしでコールバックに到達しても、コードを発行する対象が何もありません。ゲートウェイはこれを検出し、「サインイン期限切れ」として失敗する代わりに「Claude から開始してください」と表示します。

4. クイックスタート（ローカル）

npm ci
docker run -d --name mcpgw-devdb -e POSTGRES_DB=gateway -e POSTGRES_USER=gateway \
  -e POSTGRES_PASSWORD=devpassword -p 127.0.0.1:55432:5432 postgres:16-alpine
cp .env.example .env.dev   # then edit: PUBLIC_URL=http://localhost:8787, DATABASE_URL=...55432...
npx tsx test/fixtures/mockKlip.ts 5099 &      # mock KLIP, behaves like the real one
set -a; . ./.env.dev; set +a
npm run migrate
npx tsx src/index.ts

パイロットユーザーを作成します（TTY またはパイプ入力を使用可能）：

printf 'a-strong-password\na-strong-password\n' | npx tsx src/cli.ts user:add you@example.com "Your Name"

5. テスト

npm test

モック Hub は、実際のディスカバリードキュメント、実際の JWKS、実際の RS256 ID トークン、認可コードに対する PKCE 検証を備えた動作するミニ OIDC プロバイダーであり、不正なトークンを偽造するために必要なあらゆる設定項目を備えています。ネガティブケースこそが重要なのです。

モック KLIP フィクスチャは、実システムの癖を意図的に再現しています：MT とラベル付けされたキログラム、複数言語のステータス、標準の4つ以外のインコターム、null 数量、過剰納品された契約、暗黙に 100 にクランプされる limit、そしてプロンプトインジェクションペイロードを含む契約備考です。

6. デプロイ

実際の IP、ホスト名、セキュリティグループの表を含む、ホスト固有の完全な手順：deploy/RUNBOOK.md。

# on ECS-MCP
cd /opt/mcp && git pull
docker compose build gateway && docker compose up -d
curl -fsS http://127.0.0.1:8787/healthz

管理 CLI — これはコンテナ内で実行されることに注意してください。ホストには Docker のみがインストールされ、Node.js はありません：

docker compose exec -T gateway node dist/cli.js user:list
docker compose exec -T gateway node dist/cli.js audit:summary --days 7
docker compose exec -T gateway node dist/cli.js audit:export --from 2026-08-01 --to 2026-09-01 --out /tmp/audit.csv
docker compose exec -T gateway node dist/cli.js routes:verify        # probes KLIP, reports Appendix A gaps

キルスイッチ（S8） — 目標は5分未満：

docker compose exec -T gateway node dist/cli.js tokens:revoke-all --reason "incident 2026-xx"
docker compose stop gateway

アプリコンテナが異常な場合のブレークグラス：

docker compose exec -T db psql -U gateway -d gateway -c "UPDATE oauth_tokens SET revoked_at=now() WHERE revoked_at IS NULL;"

7. 付録Aはハードゲートです

src/adapters/klip/routes.ts と src/adapters/klip/fields.ts には、アダプターが依存するすべての KLIP パス、クエリパラメータ名、ページサイズ上限、レスポンスフィールド名、enum 値が保持されています。現在、すべてのエントリは未検証です。

このゲートは事務的なものではなく、実行時に強制されます。KLIP_ENV=production の場合、いずれかのルートが未検証の間、プロセスは起動を拒否します。ステージングに対して routes:verify を実行し、結果を記録し、ルートごとに verified: true を設定し、enums.verified = true を設定します。

他のどのフィールドよりも重要な2つのフィールド：

• maxLimit — KLIP が実際に受け入れる最大の limit。暗黙に 100 にクランプされる場合、KLIP_PAGE_SIZE が 1000 だと1ページが10ページになり、レイテンシ目標を破ります。

• enums.* — 正規のステータス値とインコターム値。マッピングされていないものは、デフォルト値にされることはなく、データ品質メモ付きで合計から除外されます。

8. TSD v0.9 からの逸脱

それぞれは設計レビューに由来し、その呼び出し箇所でコメントされています。

9. 未解決事項

• 付録 A の整合性確認（P1）— 本番稼働をブロックし、起動時に強制される。

• KLIP 側の K1–K4 — MCP_READONLY ロール、svc-mcp アカウント、セキュリティグループルール。

• ホスト外へのバックアップ同期とテスト済みのリストア — サイドカーはローカルのみに書き込む。

• deploy/nginx/mcp.conf の実際の企業 egress CIDR。その後、コメントアウトされた 2 つの return 403 行を有効にする。

• 30 同時ユーザーのキャパシティ NFR での負荷テスト。

• Hub クライアント登録 — ゲートウェイ自身のものを、まずテスト用 DWS Hub に登録：HUB_ISSUER、クライアント ID とシークレット、リダイレクト URI <PUBLIC_URL>/authorize/hub/callback を Hub 側に登録する。Hub の email と groups クレーム名を確認してから hub:check を実行する。Stage 7 では、本番 Hub への 2 つ目の個別登録が必要である。

• HUB_REQUIRED_GROUP を設定するかどうか、および Hub パスが本番で実証された後に BREAK_GLASS_ENABLED=false にするかどうかを決定する。