governed-mcp-gateway

Cubiczan Agent Platform

実際に稼働するエージェントのための、アイデンティティ、資金、証拠。

3つのSKUを、1つのワークスペースに。MCP クライアントは tools/call と SSE を通じて Bearer プリンシパルを維持します。委任権限がなければ支出は決済できず、上限を超える場合は人間による2つ目のキーが必要です。エージェント、CHP ロック、ハッシュ化された文書がなければ、取締役会の主張は確定できません。

SKU	ポート	ソース	役割
Governed MCP Gateway	:7474	Cubiczan/governed-mcp-gateway	すべてのツール呼び出しとSSEフレームにプリンシパルを付与します。保管された認証情報をローテーションします。ツールの許可リストを設定します。スキーマのトークンコスト台帳と、パック／必要に応じた許可による tools/list を提供します。
Agent Spend & Mandate Plane	:7475	このワークスペース	提案 → 委任 → 副署 → 決済。デフォルトはStripe、x402は決済レールです。
Auditable CFO Agent Mesh	:7476	このワークスペース	主張 → エージェント → ロック → 文書。ASC 842／606／718エンジン。HMACチェーンによる証拠パック。

共有プリミティブ（packages/shared）：CHPゲート、HMAC台帳、HTTP／SSEヘルパー。実行時のnpm依存関係はゼロです。Stripeとx402は決済レールです。テストで実ネットワークに接続することはありません。

クイックスタート

npm install
npm test
npm run gateway   # :7474
npm run spend     # :7475
npm run cfo       # :7476

デモ用Bearerキー（.env.example にも記載）：

役割	キー
ゲートウェイエージェント	mcp_agt_payops_demo
ゲートウェイの人間	mcp_human_controller_demo
ゲートウェイのリサーチ（stripe.charge なし）	mcp_agt_research_demo
支出エージェント	spend_agt_payops_demo
支出担当の人間	spend_human_controller_demo
CFOエージェント	cfo_agt_lease_demo
CFO担当の人間	cfo_human_controller_demo

ローカルAPIの最新データからREADMEカードを再生成します：

npm run shots

---

1. Governed MCP Gateway

本番環境のMCPではアイデンティティが失われます。listTools はリクエストスレッドで実行されますが、tools/call とSSEは別の場所で実行されます。このゲートウェイはBearer認証情報を プリンシパル に解決し、すべてのJSON-RPC呼び出しに挿入するとともに、すべてのSSEフレーム にも付与します。名前付きの保管庫入力はその場でローテーションでき、github_token は引き続き github_token のままです。

curl -sS -H "Authorization: Bearer mcp_agt_payops_demo" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo.ping","arguments":{"hello":"world"}}}' \
  http://127.0.0.1:7474/mcp

メソッド	パス	内容
GET	/health /healthz	稼働状態（{ ok, service, transport, mode }）。認証不要です。
POST	/mcp	ストリーミング可能なHTTP JSON-RPCの initialize、tools/list（デフォルト：セッションパック）、tools/call
GET	/mcp/sse?once=1	_meta.cubiczan.principal を含むローカルSSE通知（Vercelのパスではありません）
GET	/v1/context/tax	スキーマのトークンコスト資産とセッションレポート
POST	/v1/context/need	許可リストにあるツールをセッションパックに追加
POST	/v1/credentials/:name/rotate	人間専用の保管庫ローテーション。古いハッシュは無効になります
POST	/v1/credentials/verify	現在のハッシュとシークレットを照合

Glama リモートコネクター

Glama は、Bearer 認証を使用して https://$VERCEL_URL/mcp のステートレスな Streamable HTTP リモートをヘルスチェックできます。これはホスト型 HTTPS の経路です。Stdio（npm run mcp / Dockerfile CMD）は、引き続き Glama の Docker ビルド経路です。

Vercel プロジェクトの設定（この GitHub リポジトリをインポートします。ホスト名を勝手に設定しないでください）：

設定	値
Root Directory	.（リポジトリのルート — vercel.json + api/）
Framework Preset	Other（vercel.json で "framework": null を設定）
Fluid Compute	On（"fluid": true）
Node.js	20 以降
Install Command	npm ci && npm run build（vercel.json ですでに設定されています）
Build Command	npm run build（esbuild → dist/web.mjs。tsc を実行しないでください）
Output Directory	public（Other プリセット用の空の静的ディレクトリ。Fluid は引き続き /api を提供します）

npm run build は scripts/build-vercel.mjs（esbuild）を実行し、dist/web.mjs を生成します。api/index.mjs はこのコンパイル済みファイルをインポートします。実行時に tsx で TypeScript を読み込むことはありません。デモの許可リストと大容量スキーマのシードはバンドルにインライン化されているため、Fluid が test/fixtures/ を開くことはありません（関数には dist/** のみが含まれます）。カスタムの buildCommand の後も、Other プリセットでは静的出力フォルダーが必要です。このフォルダーに public/（outputDirectory: "public"）を使用します。Vercel ダッシュボードの Build Command がまだ tsc に設定されている場合は、TS5097 が再発しないよう、空欄にするか npm run build に設定してください。vercel.json が反映されていれば、ダッシュボードでの上書きは不要です。

環境変数（Vercel Project → Settings → Environment Variables）。公開 URL にする前に、デモ用の値をローテーションしてください。

名前	ローカルデモ	役割
GATEWAY_AGENT_KEY	mcp_agt_payops_demo	Glama コネクター用 Bearer（PayOps 許可リスト）
GATEWAY_HUMAN_KEY	mcp_human_controller_demo	Vault / ロック
GATEWAY_RESEARCH_KEY	mcp_agt_research_demo	Research 許可リスト（stripe.charge なし）
SPEND_PLANE_URL	未設定	:7475 へのオプションのフック

デプロイ後の Glama コネクターのフィールド（$VERCEL_URL を、Vercel が表示するデプロイ先ホストに置き換えます）：

• URL：https://$VERCEL_URL/mcp
• Transport：Streamable HTTP
• Authorization：Bearer $GATEWAY_AGENT_KEY

ローカルでのスモークテスト（公開ホスト名は不要）：

npm run mcp:http:smoke
# or:
npm run gateway
curl -sS http://127.0.0.1:7474/health
curl -sS -H "Authorization: Bearer mcp_agt_payops_demo" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  http://127.0.0.1:7474/mcp

initialize は Mcp-Session-Id を発行しません。セッションパックより多く必要な場合は、同じ tools/list で params.pack / params.need を渡してください。GET /mcp は 405 です（リモートでは SSE を固定接続しません）。

---

2. エージェント支出・委任プレーン

エージェントが提案し、委任権限が承認します。金額が自動承認の上限を超える場合は、人間が副署します。提案したエージェント自身が副署することはできません。決済手段は、デフォルトでは Stripe のメーターイベント、明示的に指定した場合は x402 の支払い要求です。この MVP ではチェーン呼び出しは行いません。

curl -sS -H "Authorization: Bearer spend_agt_payops_demo" \
  -H "Content-Type: application/json" \
  -d '{"agent":"agt_payops","merchant":{"name":"Stripe","url":"https://stripe.com","country":"US"},"total":"12.00","rationale":"tool meter"}' \
  http://127.0.0.1:7475/v1/proposals

メソッド	パス	内容
POST	/v1/mandates	オペレーターが残額分の補償を作成します
POST	/v1/proposals	エージェントが提案します。レーンは auto | approval | blocked です
POST	/v1/countersign	人間による第2のキーです。エージェントは拒否されます
POST	/v1/settle	{ "rail": "stripe" } または "x402"

3. 監査可能な CFO エージェントメッシュ

取締役会向けの主張は、エージェント、LOCKED の CHP 状態、そして少なくとも 1 つのソースドキュメントのハッシュが揃うまで完了ではありません。エンジンは測定を行います（ASC 842 リースのロールフォワード、ASC 606 制約付き POC、ASC 718 SBC）。法律上の事実を判断するものではありません。トークンの使用量は、同じ HMAC チェーン台帳上のソースとして記録されます。

curl -sS -H "Authorization: Bearer cfo_agt_lease_demo" \
  -H "Content-Type: application/json" \
  -d '{"title":"AI spend is $12.00 this period","narrative":"Token ledger supports the board claim.","agentId":"agt_lease"}' \
  http://127.0.0.1:7476/v1/claims

メソッド	パス	内容
POST	/v1/claims	主張を開始
POST	/v1/claims/:id/documents	名前付きソースを添付。SHA-256 を保存
POST	/v1/claims/:id/lock	人間がロック → LOCKED
POST	/v1/engines/lease	ASC 842 の分類とロールフォワード
GET	/v1/evidence/:id	封印。ドキュメントがない場合、またはロックされていない場合は 400

仕様

OpenSpec の変更：ship-three-sku-platform、tools-list-token-tax、glama-streamable-http-remote、vercel-compiled-fluid-entry、vercel-public-output-directory。

ライセンス

MIT