# Auth0 Forms MCP

An Auth0 Custom Extension that exposes an Auth0 Form as an authenticated MCP App. It starts from the [Auth0 Who Am I MCP template](https://github.com/mustafadeel/auth0-whoami-mcp-template), retains its Node 22, OAuth, and tenant-provisioning contract, and registers the Form through [`@auth0/agent-components`](https://github.com/mustafadeel/universal-components-agents).

The included POC Form in `genai-574273613646507.ca.auth0.com` is `MCP Hello World` (`ap_vJfTyBRtMJw6HD8Jp8vz4d`). It is a standalone Form: leave the session settings empty.

## Configure and deploy

1. Keep this repository public. The Auth0 Custom Extension loader reads `webtask.json`, `index.js`, and generated build artifacts from `master`.
2. Import or fully update this repository as an Auth0 Custom Extension. Set:

   | Setting | Value for the POC |
   | --- | --- |
   | `FORM_ID` | `ap_vJfTyBRtMJw6HD8Jp8vz4d` |
   | `FORM_NAME` | `Hello World` |
   | `FORM_DESCRIPTION` | `Open this form to display the Hello World MCP App POC.` |

   Leave `FORM_SESSION_FIELD`, `AUTH0_FORMS_TRUST_SECRET`, `FORMS_ORIGIN`, and `PUBLIC_BASE_URL` blank.

3. Open the installed extension and select **Sign in and provision**. The Dashboard-admin-protected setup route creates or updates the RS256 Auth0 API resource server whose identifier is the exact displayed MCP URL. It also configures `subject_type_authorization` to allow applications by default and sets the tenant's `resource_parameter_profile` to `compatibility`.
4. Import [auth0-ext-wellknown](https://github.com/mustafadeel/auth0-ext-wellknown) as a separate Custom Extension in the same tenant. Keep its name `.well-known` and set:

   | Setting | Value |
   | --- | --- |
   | `MCP_RESOURCE_URL` | `https://genai-574273613646507.ca.webtask.run/auth0-forms-mcp/mcp` |
   | `AUTH0_TENANT_ORIGIN` | `https://genai-574273613646507.ca.auth0.com` |
   | `RESOURCE_NAME` | `MCP Hello World` |

5. Use the setup page to promote an existing connection to domain-level if none is already configured. Third-party and dynamically registered MCP clients need one to show Universal Login.
6. Connect an OAuth-capable client to `https://genai-574273613646507.ca.webtask.run/auth0-forms-mcp/mcp`.

## Implementation notes

The server creates a fresh MCP server and Streamable HTTP transport per request, suitable for the stateless Webtask runtime. `@auth0/agent-components` exposes the Form through an `open_form_*` MCP tool and a `ui://` resource; the Form submits directly to Auth0 and only completion status reaches the agent.

Provisioning is the only operation that changes tenant configuration. It runs behind the Dashboard-admin setup session and requires the extension-managed Management API client to have resource-server, connection, and tenant-settings read/update scopes. Those scopes are declared in the manifest and require a full extension reinstall/update when they change.

For a flow or router Form, set `FORM_SESSION_FIELD` to the Form's hidden field and `AUTH0_FORMS_TRUST_SECRET` to the trusted-session secret configured for Forms. The server verifies the caller’s Auth0 access token before the SDK mints the trusted Form session token.

## Build and verify

```sh
npm install
npm test
```

Commit `index.js`, `build/bundle.js`, and every file in `dist/`, then push the same commit to `main` and `master` before importing it into Auth0.