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

Verwandeln Sie ein Auth0 Form in eine MCP App — eine interaktive UI, die ein Model Context Protocol-Server einem MCP-Client bereitstellt und in einem Sandbox-iframe rendert. Das ist Auth0 Universal Components for Agents: Jedes Auth0 Form wird zu einer direkt einsetzbaren, agentenaufrufbaren UI, ganz ohne Auth0 Action.

Status: Proof of Concept. Funktioniert Ende-zu-Ende mit der offiziellen MCP Apps-Fähigkeit (SEP-1865), dem MCP Inspector und CopilotKit (siehe examples/copilotkit-poc).

Warum

Auth0 Forms werden normalerweise nur innerhalb einer Auth0 Action während des Universal Login gerendert. Das dx-flows-sdk hat das entkoppelt: Ein Formular kann über das Browser-Bundle außerhalb einer Login-Weiterleitung eingebettet werden. MCP Apps erlauben einem Server, einem Client interaktives HTML zum Rendern in einem Sandbox-iframe zu übergeben. Beides zusammen ergibt: Ein Agent kann ein echtes, voll funktionsfähiges Auth0 Form — Sign-up, Consent, Profil, Zahlung — als eines seiner Tools verfügbar machen.

So funktioniert es

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)

Das Formular besitzt seine Daten. Das Auth0 Form übermittelt nativ an sein Auth0-Backend. Die MCP-Schicht liest oder überträgt niemals Feldwerte — sie meldet nur einen Abschlussstatus (completed / cancelled / errored plus optional ein Weiterleitungsziel), damit der Agent weiß, dass der Benutzer fertig ist.

Pakete

Verwendung

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)

Jedes Formular registriert:

• ein Tool open_form_<slug>, dessen _meta.ui.resourceUri auf … zeigt

• eine Ressource ui://agent-components/<formId>, die das Formular-App-HTML plus einen CSP-Block zurückgibt.

CSP

Der Host rendert die Ressource unter einer strikten Standard-Richtlinie (default-src 'none'). @auth0/agent-components nimmt Ihre tenantOrigin automatisch in beide Zulassungslisten auf:

• csp.resourceDomains — damit forms.js, Styles, Schriften und Bilder geladen werden, und

• csp.connectDomains — damit der fetch des Bundles zu /forms/api/... funktioniert.

Wenn ein Formularschritt ein iframe einer anderen Origin einbettet (Stripe, ein Social-Provider, ein Captcha), deklarieren Sie es:

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

Beobachten Sie beim ersten Rendern eines neuen Formulars die Browser-Konsole: Jede CSP-Verletzung verrät Ihnen genau, welche Origin Sie hinzufügen müssen.

Sitzungsgestützte Formulare (Flow-/Router-Formulare)

Formulare mit einem FLOW/ROUTER-Knoten benötigen eine authentifizierte Sitzung — andernfalls schlägt der Schritt nach dem Router mit ERR_INVALID_FORM_SESSION fehl. Der Mechanismus (mit dem Forms-Team bestätigt, Ende-zu-Ende verifiziert):

1. Deklarieren Sie ein verstecktes Feld im Formular (z. B. session_token).

2. Der Flow des Formulars liest es — z. B. eine Update User-Aktion mit user_id: {{fields.session_token}}.

3. Der MCP-Server, der als OAuth-Ressourcenserver fungiert, verifiziert das Auth0-Token des Aufrufers, ermittelt die sub des Benutzers, erstellt ein kurzlebiges, vertrauenswürdiges JWT für diese sub (signiert mit einem gemeinsamen Geheimnis, dem das Forms-Backend vertraut) und injiziert es pro Anfrage in das versteckte Feld.

Markieren Sie das Formular als sitzungsbewusst:

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

…und initialisieren Sie den Client mit der serverbezogenen Vertrauenskonfiguration plus einem Resolver, der die verifizierte Identität ausliest (verifier und subFromExtra stammen aus dem /auth-Unterpfad, unterstützt von @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);

Der POC-Server (examples/poc-server) implementiert den vollständigen Ablauf: createAuth0Verifier (→ @auth0/auth0-api-js), einen ProtectedResourceMetadataBuilder-Metadata-Endpunkt und requireBearerAuth — so ermöglicht eine 401 + WWW-Authenticate-Herausforderung dem Client, den Auth0-OAuth-Ablauf auszuführen. Token, sub und erstelltes JWT gelangen nie in den MCP-Modellkontext — das erstellte Token reist über embed().fields ausschließlich an das Auth0-Forms-Backend.

Hinweis: Ein abgeschlossener Auth0-Forms-Journey ist derzeit nur einmal verwendbar (das erneute Senden eines verbrauchten Journeys gibt ERR_INVALID_FORM_SESSION zurück). Universal Portals EPIC 7 fügt erneut abschließbare Journeys hinzu. Die MCP App schließt einmal ab und meldet den Status, sodass ein neuer Tool-Aufruf einen neuen Journey erhält — erneutes Senden ist nicht Teil des Ablaufs.

Zeitpunkt der Registrierung

Das MCP SDK verbietet, eine Fähigkeit nach server.connect(transport) hinzuzufügen. Zwei unterstützte Muster:

• Vor dem Connect registrieren (am einfachsten) mit assumeUiSupport: true. Richtig für UI-fähige Clients (MCP Inspector, Claude). Genau das macht der POC.

• Dynamische Steuerung pro Client (assumeUiSupport: "auto", der Standard): Rufen Sie registerAuth0Forms aus server.server.oninitialized auf, damit die Fähigkeiten des Clients bekannt sind — und konstruieren Sie den Server mit { capabilities: { tools: {}, resources: {} } }, oder registrieren Sie vor dem Connect ein Tool + eine Ressource, damit die Registrierung nach dem Connect nicht versucht, eine neue Fähigkeit hinzuzufügen.

Entwicklung

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)

Lizenz

MIT