@auth0/agent-components — Auth0 エージェント向けユニバーサルコンポーネント

Auth0 Form を MCP App に変えます — Model Context Protocol サーバーが MCP クライアントに提供する、サンドボックス化された iframe 内でレンダリングされるインタラクティブ UI です。これは Auth0 エージェント向けユニバーサルコンポーネントです。あらゆる Auth0 Form が、Auth0 Action を必要とせずに、そのままエージェントが呼び出せる UI になります。

ステータス: 概念実証。公式の MCP Apps 機能（SEP-1865）、MCP Inspector、 および CopilotKit（examples/copilotkit-poc を参照）に対してエンドツーエンドで動作します。

なぜ

Auth0 Forms は通常、Universal Login 中の Auth0 Action 内でのみレンダリングされます。dx-flows-sdk がこれを分離しました。フォームはログインリダイレクトの外でブラウザバンドル経由で埋め込むことができます。MCP Apps はサーバーがクライアントにインタラクティブな HTML を渡し、サンドボックス化された iframe 内でレンダリングできるようにします。これらを組み合わせると、エージェントは本物の完全に機能する Auth0 Form — サインアップ、同意、プロフィール、支払い — を自身のツールの1つとして表示できます。

仕組み

MCP host (e.g. MCP Inspector, CopilotKit)
 └─ sandboxed iframe  ← our ui:// HTML resource (text/html;profile=mcp-app)
      ├─ <script src="https://<tenant>/forms/sdk/forms.js">
      ├─ Auth0Forms.embed(formId, "#root", { fields: { session_token } })
      │    └─ form submits to its OWN Auth0 backend (/forms/api/...)  ← we never see the data
      └─ bridge: on af-submitForm-success → app.updateModelContext({ status: "completed" })
                                          → app.requestTeardown()   (close the app view)
                  on af-redirect          → app.openLink(url)       (never navigates the iframe)

フォームは自身のデータを所有します。 Auth0 Form はネイティブに Auth0 バックエンドへ送信します。MCP レイヤーはフィールド値を読み取ったり送信したりすることはなく、完了ステータス（completed / cancelled / errored、およびオプションのリダイレクト先）のみを報告するため、エージェントはユーザーが完了したことを把握できます。

パッケージ

使用方法

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerAuth0Forms } from "@auth0/agent-components";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

await registerAuth0Forms(
  server,
  [
    {
      formId: "your-form-id",
      tenantOrigin: "https://your-tenant.us.auth0.com",
      // inputMode: "prefill",         // expose form fields as optional agent inputs
      // ui: { csp: { frameDomains: ["https://js.stripe.com"] } }, // for payment/social steps
      onComplete: (r) => console.log(r.formId, r.status),         // status only — no field data
    },
  ],
  { assumeUiSupport: true }, // register before connect; see "Registration timing"
);

// ...connect your transport (StreamableHTTP / stdio / SSE)

各フォームは以下を登録します:

• ツール open_form_<slug>。その _meta.ui.resourceUri は次を指します…

• フォームアプリの HTML + CSP ブロックを返す ui://agent-components/<formId> リソース。

CSP

ホストは厳格なデフォルトポリシー（default-src 'none'）の下でリソースをレンダリングします。@auth0/agent-components は tenantOrigin を以下の両方に自動的にホワイトリスト登録します:

• csp.resourceDomains — forms.js、スタイル、フォント、画像が読み込まれるように、および

• csp.connectDomains — バンドルの /forms/api/... への fetch が機能するように。

フォームのステップが別のオリジンの iframe（Stripe、ソーシャルプロバイダー、キャプチャ）をネストする場合は、それを宣言します:

ui: { csp: { frameDomains: ["https://js.stripe.com", "https://hooks.stripe.com"] } }

新しいフォームを初めてレンダリングするときにブラウザコンソールを確認してください。CSP 違反があれば、追加すべきオリジンが正確にわかります。

セッションベースのフォーム（フロー/ルーターフォーム）

FLOW/ROUTER ノードを持つフォームには認証済みセッションが必要です — そうでないと、ルーターの後のステップが ERR_INVALID_FORM_SESSION で失敗します。この仕組み（Forms チームに確認済み、エンドツーエンドで検証済み）:

1. フォームに非表示フィールドを宣言します（例: session_token）。

2. フォームのフローがそれを読み取ります — 例: user_id: {{fields.session_token}} を持つ Update User アクション。

3. MCP サーバーはOAuth リソースサーバーとして機能し、呼び出し元の Auth0 トークンを検証し、ユーザーの sub を解決し、それに対する短期間有効な信頼済み JWT を発行し（Forms バックエンドが信頼する共有シークレットで署名）、リクエストごとに非表示フィールドに注入します。

フォームをセッション対応としてマークします:

{
  formId: "ap_...",
  session: { field: "session_token" },   // must match the form's hidden field
}

…そして、サーバースコープの信頼設定と、検証済み ID を読み取るリゾルバー（verifier と subFromExtra は /auth サブパスから取得され、@auth0/auth0-api-js によって支えられています）を指定してクライアントを初期化します:

import { createAgentComponents } from "@auth0/agent-components";
import { subFromExtra } from "@auth0/agent-components/auth";

const agentComponents = createAgentComponents({
  tenantOrigin: "https://your-tenant.auth0.com",
  assumeUiSupport: true,
  sessionTrust: { secret: process.env.FORMS_TRUST_SECRET! }, // shared with the Forms backend
  resolveUserSub: subFromExtra,                    // returns the caller's `sub`, or undefined
});
await agentComponents.register(server, forms);

POC サーバー（examples/poc-server）は完全なフローを配線します: createAuth0Verifier（→ @auth0/auth0-api-js）、ProtectedResourceMetadataBuilder メタデータエンドポイント、および requireBearerAuth — これにより、401 + WWW-Authenticate チャレンジでクライアントが Auth0 OAuth フローを実行できます。トークン/sub/発行済み JWT は MCP モデルコンテキストに入ることはありません — 発行済みトークンは embed().fields を介して Auth0 Forms バックエンドのみに送られます。

注: 完了した Auth0 Forms ジャーニーは現在のところ使い捨てです（使用済みジャーニーを再送信すると ERR_INVALID_FORM_SESSION が返されます）。Universal Portals EPIC 7 で再完了可能なジャーニーが追加されます。MCP App は一度完了してステータスを報告するため、新しいツール呼び出しは新しいジャーニーを取得します — 再送信はフローの一部ではありません。

登録タイミング

MCP SDK は server.connect(transport) 後に機能を追加することを禁止しています。2つのサポートされるパターン:

• 接続前に登録（最も簡単）assumeUiSupport: true を使用。UI 対応クライアント（MCP Inspector、Claude）に適しています。POC はこれを行います。

• クライアントごとの動的ゲーティング（assumeUiSupport: "auto"、デフォルト）: クライアントの機能が判明するように server.server.oninitialized から registerAuth0Forms を呼び出します — そしてサーバーを { capabilities: { tools: {}, resources: {} } } で構築するか、接続前に1つのツールと1つのリソースを登録して、接続後の登録が新しい機能を追加しようとしないようにします。

開発

npm install
npm run build      # builds all packages (agent-components builds its bridge first)
npm test           # unit tests (form→tool, ui-template CSP, bridge status-only contract)

ライセンス

MIT