@auth0/agent-components — Auth0 Universal Components for Agents

Auth0 Form을 MCP App으로 전환하세요. Model Context Protocol 서버가 MCP 클라이언트에 제공하는 대화형 UI로, 샌드박스 iframe에서 렌더링됩니다. 이것이 Auth0 Universal Components for Agents입니다. 모든 Auth0 Form이 별도의 Auth0 Action 없이도 바로 사용 가능한 에이전트 호출형 UI가 됩니다.

상태: 개념 증명(PoC). 공식 MCP Apps 기능(SEP-1865), MCP Inspector, CopilotKit과 함께 엔드투엔드로 동작합니다(examples/copilotkit-poc 참조).

이유

Auth0 Forms는 일반적으로 Universal Login 중 Auth0 Action 내부에서만 렌더링됩니다. dx-flows-sdk가 이를 분리했습니다. 이제 폼을 로그인 리디렉션 밖에서 브라우저 번들을 통해 삽입할 수 있습니다. MCP Apps는 서버가 클라이언트에 대화형 HTML을 전달하여 샌드박스 iframe에서 렌더링하도록 합니다. 이 둘을 결합하면 에이전트는 가입(sign-up), 동의(consent), 프로필(profile), 결제(payment) 등 실제 완전한 기능을 갖춘 Auth0 Form을 도구 중 하나로 표시할 수 있습니다.

작동 방식

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)

각 폼은 다음을 등록합니다.

• _meta.ui.resourceUri가 ...을 가리키는 open_form_<slug> 도구

• 폼 앱 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 폼)

FLOW/ROUTER 노드가 있는 폼은 인증된 세션이 필요합니다. 그렇지 않으면 라우터 다음 단계가 ERR_INVALID_FORM_SESSION 오류로 실패합니다. 이 메커니즘은(Forms 팀과 확인했고 엔드투엔드로 검증했습니다):

1. 폼에 숨김 필드를 선언합니다(예: session_token).

2. 폼의 플로우가 이를 읽습니다 — 예: user_id: {{fields.session_token}}가 있는 Update User 액션.

3. OAuth 리소스 서버 역할을 하는 MCP 서버가 호출자의 Auth0 토큰을 검증하고 사용자의 sub를 확인한 다음, 그 사용자에 대해 단기 신뢰 JWT를 발급하고(Forms 백엔드가 신뢰하는 공유 시크릿으로 서명), 요청별로 해당 JWT를 숨김 필드에 주입합니다.

폼을 세션 인식으로 표시하세요:

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

...그리고 검증된 ID를 읽는 리졸버 + 서버 범위의 신뢰 구성으로 클라이언트를 초기화합니다(검증기와 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 여정은 현재 1회용입니다(사용된 여정을 다시 제출하면 ERR_INVALID_FORM_SESSION이 반환됩니다). Universal Portals EPIC 7에는 다시 완료할 수 있는 여정이 추가됩니다. MCP App은 한 번 완료하고 상태를 보고하므로 새 도구 호출은 새 여정을 얻습니다. 재제출은 흐름에 포함되지 않습니다.

등록 시점

MCP SDK는 server.connect(transport) 이후에 capability(기능)를 추가하는 것을 금지합니다. 지원되는 두 가지 패턴이 있습니다.

• 연결 전 등록(가장 간단함): assumeUiSupport: true를 사용합니다. UI를 지원하는 클라이언트(MCP Inspector, Claude)에 적합합니다. POC가 사용하는 방식입니다.

• 클라이언트별 동적 게이팅(assumeUiSupport: "auto", 기본값): server.server.oninitialized에서 registerAuth0Forms를 호출하여 클라이언트의 기능을 파악합니다. 그리고 { capabilities: { tools: {}, resources: {} } }로 서버를 구성하거나, 연결 전에 도구 하나 + 리소스 하나를 등록하여 연결 후 등록이 새 기능을 추가하려고 시도하지 않도록 합니다.

개발

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