Auth0 Forms MCP Custom Extension

This repository packages the MCP server from auth0-agent-components/examples/poc-server in the same format as Auth0's Delegated Administration Extension. The package exposes one Auth0 Form as an MCP App at the deployed extension URL plus /mcp.

What is in the package

• package.json contains the auth0-extension manifest that the Custom Extension importer reads.
• webtask.json selects the Node 22 Webtask runtime used by the extension deployment.
• src/webtask.ts is the Webtask handler expected by the extension runtime.
• src/app.ts adapts the POC server to a stateless Streamable HTTP MCP transport.
• dist/package.zip, created by npm run build, is the file to import into the Custom Extension workflow.
• index.js and build/bundle.js support the legacy repository loader that fetches those paths from the master branch.

Configure the extension

During import, set these settings:

Setting	Required	Purpose
AUTH0_TENANT_ORIGIN	No	Optional canonical tenant issuer override; defaults to the tenant supplied by the extension runtime.
FORM_ID	Yes	The Auth0 Form ID to expose.
AUTH0_FORMS_TRUST_SECRET	Session forms	Shared secret for the Forms session JWT.
FORM_SESSION_FIELD	Session forms	Hidden Form field receiving the session JWT, normally session_token.
AUTH0_AUDIENCE	External endpoint only	Optional audience override for an OAuth proxy or custom endpoint.
PUBLIC_BASE_URL	OAuth proxy	Public proxy origin, without a trailing slash.
FORMS_ORIGIN	No	Custom domain that hosts the Forms bundle.
MCP_AUTH	No	Leave on in production. Set off only for no-session local development.

FORM_DESCRIPTION and FORM_NAME control the model-facing tool description and tool name.

Provision the tenant API

The extension requests an extension-owned Management API client with only read:resource_servers and create:resource_servers. It reads the tenant domain from the runtime and creates or reuses an Auth0 API whose identifier is the exact installed MCP URL.

1. Perform a full Custom Extension update or reinstall after importing version 0.3.0 so Auth0 creates the managed client and grants its declared scopes.
2. Open the extension landing page and select Sign in and provision.
3. Complete the tenant-admin login. The landing page creates or reuses the required API audience, then shows its status.
4. Connect the MCP client to the displayed MCP endpoint.

Provisioning is available only through the Dashboard-admin login flow. Public MCP, health, and discovery routes never modify tenant configuration. AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_DOMAIN, and EXTENSION_SECRET are runtime-managed values; do not add them to extension settings or log them.

Build an importable package

The local @auth0/agent-components dependency points to the sibling source repository because it is not available from the configured npm registry. Keep these two directories adjacent while building:

/Users/adeel.mustafa/
  auth0-agent-components/
  auth0-mcp-custom-extension/

Then run:

npm install
npm run build

The importer artifact is dist/package.zip. It contains the bundled extension.js and a runtime-only package.json; neither references the sibling checkout once imported.

The repository also publishes a master branch because the legacy Custom Extension loader fetches index.js and build/bundle.js from that branch. Do not remove the generated build/bundle.js file.

Import and connect

1. Import dist/package.zip into the same Custom Extension workflow that accepts the Delegated Administration Extension package format.
2. Enter the configuration values above.
3. Open the installed extension and complete Sign in and provision once.
4. Register the displayed MCP URL in an MCP client. The extension advertises its protected-resource metadata at /.well-known/oauth-protected-resource.

The extension uses a stateless MCP transport because Webtask-style extension runtimes do not guarantee that the same process handles successive requests. It does not support server-initiated notifications or resumable SSE sessions.

OAuth discovery companion

Webtask routes are scoped under the extension name, so the platform cannot serve the host-root OAuth protected-resource metadata URL. Use the companion Custom Extension at https://github.com/mustafadeel/auth0-ext-wellknown; it stays in the same Auth0 tenant and does not require an external proxy.

1. Import auth0-ext-wellknown into the same tenant as a second Custom Extension. Keep its name as .well-known and useHashName as false.
2. Set MCP_RESOURCE_URL to the displayed MCP URL, AUTH0_TENANT_ORIGIN to the canonical tenant issuer, and optionally set RESOURCE_NAME.
3. Connect the client to the MCP URL from this extension, never the companion extension URL.

For an intentionally external proxy or custom domain, set PUBLIC_BASE_URL and AUTH0_AUDIENCE to the proxy's exact /mcp URL before provisioning.

Local development

Copy .env.example to .env.local, configure it, then run:

npm run dev

Connect the MCP Inspector to http://localhost:3000/mcp.