ProGear MCP サーバー

ProGear バスケットボール用品デモのための単一 MCP ゲートウェイ。Inventory・Customer・Sales・Pricing の4つのドメインをホストし、各ドメインは実際の MCP プロトコル（Streamable HTTP トランスポート）で通信します。認証はご自身の Okta 組織（ドメインごとに独自の Custom Authorization Server とスコープセット）によって保護されています。

これは ProGearSalesAI を意図的に小さくした兄弟プロジェクトです。Auth0 FGA も LangGraph オーケストレーターもフロントエンドもありません。ゲートウェイ自体は渡されたベアラートークンを検証するだけであり、呼び出し元がどのようにトークンを取得したかは関知しません。packages/local-tester（ローカルのみ・未デプロイ）は、呼び出し元がトークンを取得する方法の一例を示しています。人間による PKCE ログインと、エージェントによる ID-JAG 交換でそのトークンをミントする方法（元のアプリの Cross-App Access フローを反映）です。

デプロイ構成

1つのプロセス、1つの Render サービス、1つのビルド/起動コマンド。 packages/gateway は、単一の Express アプリの背後にある異なるパスに4つのドメインすべてをマウントします。

各マウントは、同じプロセス内で実行されているにもかかわらず、独自の Okta Custom Authorization Server（ドメインごとに異なる issuer/audience）に対して検証を行います。インベントリ認証サーバー用に発行されたトークンは /customer/mcp に対しては使用できません。また、マウント内では各ツール呼び出しが、呼び出し元のトークンに付与されたスコープに対して必要なスコープをチェックします（inventory:write がないトークンは check_stock を呼び出せますが、update_inventory_quantity は呼び出せません）。

packages/mcp-inventory・mcp-customer・mcp-sales・mcp-pricing は、スタンドアロンサーバーとしても機能します（独自の server.ts + /mcp + /health、単一ドメインの環境変数）。将来、別々のデプロイに分割したい場合に備えてです。ゲートウェイは各ツールの登録ロジック（./tools エクスポート）をインポートし、.listen() を自分で呼び出す代わりに独自の認証設定の下でマウントするだけです。

Related MCP server: Meraki MCP Server

データ

ProGearSalesAI デモデータセットの移植済みスナップショットからシードされます。インベントリ SKU 90件、価格エントリ90件、顧客34件、ティア/数量割引テーブル（packages/shared/src/data/initial_data.json）。販売注文/見積はメモリ内のみです。プロセスの再起動ですべての状態がリセットされます — これはツールサーバーであり、システムオブレコード（記録システム）ではありません。

プロジェクト構成

packages/
  shared/            # ported data + store, JWKS auth + scope enforcement, HTTP/MCP transport helper
  mcp-inventory/      mcp-customer/      mcp-sales/      mcp-pricing/   # tool definitions + standalone entrypoint each
  gateway/            # the actual deployment: mounts all 4 at /inventory, /customer, /sales, /pricing
  local-tester/       # local-only: PKCE login + agent ID-JAG exchange, calls the deployed gateway (see its own README)

ローカル開発

npm install
npm run build            # builds shared + all 4 domains + gateway, in dependency order

npm run dev:gateway       # tsx watch, all 4 mounts on one port (default 3000)

マウントに関連する Okta 環境変数が設定されていない場合、そのマウントは ALLOW_INSECURE=true を設定しない限り、すべての /mcp リクエストに対して 500 を返します。ALLOW_INSECURE=true を設定するとトークン検証をスキップし、すべてのマウントにすべてのスコープを付与します。これはローカル開発専用であり、デプロイ環境では決して設定しないでください。

Okta のセットアップ

OKTA_DOMAIN を一度設定し、各ドメインに OKTA_<DOMAIN>_AUTH_SERVER_ID と OKTA_<DOMAIN>_AUDIENCE を設定します。これらは ProGearSalesAI バックエンドで既に使用されているのと完全に同じ環境変数名です（OKTA_CUSTOMER_AUTH_SERVER_ID・OKTA_INVENTORY_AUDIENCE など）。したがって、既存の値をそのままコピーできます。

OKTA_DOMAIN=https://your-org.okta.com

OKTA_INVENTORY_AUTH_SERVER_ID=...   OKTA_INVENTORY_AUDIENCE=api://progear-inventory
OKTA_CUSTOMER_AUTH_SERVER_ID=...    OKTA_CUSTOMER_AUDIENCE=api://progear-customer
OKTA_SALES_AUTH_SERVER_ID=...       OKTA_SALES_AUDIENCE=api://progear-sales
OKTA_PRICING_AUTH_SERVER_ID=...     OKTA_PRICING_AUDIENCE=api://progear-pricing

完全なリストは .env.example を参照してください。ProGearSalesAI 形式の .env のうちここでは適用されない変数（Anthropic キー、CORS、AI エージェント自身の秘密鍵/クライアント ID — このゲートウェイは受信トークンを検証するだけで、自己発行はしません）も含めて確認できます。トークンは各ドメイン自身の Okta JWKS エンドポイント（jose の createRemoteJWKSet）に対して、署名・issuer・audience によって検証されます。この側では共有シークレットは不要です。

Render へのデプロイ

ダッシュボードまたは同梱の Blueprint のいずれかによる単一サービスです。

手動（New → Web Service）:

Blueprint: リポジトリルートの render.yaml は、同じ単一の progear-mcp-gateway サービスを定義しています。New → Blueprint でこのリポジトリを指定し、プロンプトで表示される9つの Okta 環境変数（sync: false とマーク）を入力します。

エージェントへの接続

各マウントは、POST/GET/DELETE <mount>/mcp で MCP over Streamable HTTP を公開します（ステートレス — リクエスト間のセッション永続化なし）。さらに、独自の GET <mount>/health と、すべてのマウントを一覧表示するトップレベルの GET /health もあります。

関連する Custom Authorization Server とスコープ用のアクセストークンを Okta から取得し（例：サービス/エージェント ID 用の client-credentials グラント）、次に:

Claude Code CLI:

claude mcp add --transport http progear-inventory \
  https://<your-render-url>/inventory/mcp \
  --header "Authorization: Bearer <token>"

ドメインごとに、そのドメインの audience にスコープされたトークンを使用して繰り返します（/customer/mcp・/sales/mcp・/pricing/mcp）。

その他の MCP クライアント / エージェント SDK: すべてのリクエストに Authorization: Bearer <token> ヘッダーを付けて、マウントの /mcp URL を指定します。

OAuth ディスカバリ（静的トークンなし）

MCP 認証仕様を実装するクライアントは、トークンを渡される代わりに Okta を自分で発見できます。各マウントは、ゲートウェイのルートで RFC 9728 保護リソースメタデータを公開します。これは、それが記述するエンドポイントにパススコープされています。

GET /.well-known/oauth-protected-resource/inventory/mcp
GET /.well-known/oauth-protected-resource/customer/mcp
GET /.well-known/oauth-protected-resource/sales/mcp
GET /.well-known/oauth-protected-resource/pricing/mcp

{
  "resource": "https://<your-render-url>/inventory/mcp",
  "authorization_servers": ["https://your-org.okta.com/oauth2/<inventory-auth-server-id>"],
  "scopes_supported": ["inventory:read", "inventory:write", "inventory:alert"],
  "bearer_methods_supported": ["header"],
  "resource_name": "ProGear Inventory MCP"
}

/mcp からの 401 応答にもポインターが含まれるため、エンドポイントを事前知識なしで呼び出したクライアントは認証先を知ることができます。

WWW-Authenticate: Bearer resource_metadata="https://<your-render-url>/.well-known/oauth-protected-resource/inventory/mcp"

（トークンが提示されたが検証に失敗した場合、チャレンジには追加で error="invalid_token" と error_description が含まれます。）

これらのドキュメント内の URL は、受信リクエスト（X-Forwarded-Proto + Host、trust proxy はオン — Render では正しく動作）から導出されます。ゲートウェイの前にある何かが Host ヘッダーを書き換える場合のみ PUBLIC_BASE_URL=https://<your-render-url> を設定してください。

クライアントがフローを完了できるようにするには、Okta 組織で OIDC パブリッククライアント（Authorization Code + PKCE）を登録し、クライアントのリダイレクト URI を追加して（Claude.ai は https://claude.ai/api/mcp/auth_callback を使用）、その Custom Authorization Server のアクセスポリシーでドメインのスコープを付与します。

完全なゼロ設定接続にまだ欠けているもの: 動的クライアント登録。Okta の /oauth2/v1/clients エンドポイントには SSWS API トークンが必要なため、匿名登録用にアドバタイズできません。DCR を必須とするクライアント（現時点では VS Code / Copilot）は、その前に登録シムが必要です。事前登録済みの client_id を受け入れるクライアントは、上記のディスカバリをそのまま使用できます。