Auth0 Who Am I MCP Template

Fork this public template to create an Auth0 Custom Extension that exposes an authenticated Streamable HTTP MCP server. Its whoami tool returns safe claims for the current Auth0 user.

Forking is required, not optional — the legacy Custom Extension importer reads webtask.json and generated build artifacts directly from a specific GitHub repo URL at both preview and install time, so there is no way to install a shared/parameterized copy of this template. Forking means taking on the whole deployment contract below: generated build output (index.js, build/bundle.js, dist/) is committed to git rather than gitignored, main and master must be kept in sync by hand, and the fork must stay public. This is more upkeep than a typical npm-installed dependency; budget for it before adopting this template.

The template targets Node 22, derives the tenant issuer and installed MCP URL at runtime, and creates or reuses the Auth0 API resource server from a tenant-admin setup flow. It does not ask users to enter tenant or direct MCP URLs in extension settings.

See SKILL.md for the full manifest layout, route table, and a troubleshooting section covering every non-obvious failure mode hit while building this template — check there first if something that used to work stops working.

Fork and customize

1. Fork this repository and keep the fork public.

2. Update webtask.json and package.json with your title, extension name, author, repository URL, and version.

3. Add or replace tools in src/mcp-server.ts (see Add a tool below). Everything else in src/app.ts — bearer-token verification, the setup routes, .well-known metadata — is deployment plumbing shared by every tool; leave it intact.

4. Run npm install and npm test with your organization's managed npm authentication.

5. Commit generated index.js, build/bundle.js, dist/extension.js, dist/package.json, and dist/package.zip.

6. Push the same release to both main and master. The legacy Custom Extension importer fetches generated loader files from master. After merging any change into main, fast-forward master to match (git checkout master && git merge --ff-only origin/main && git push origin master) — the two branches drifting apart is a common source of confusing, hard-to-reproduce bugs.

Related MCP server: oauth-auth0-mcp-prototype

Add a tool

Tools live in src/mcp-server.ts, registered on the McpServer instance inside createMcpServer(). Add a new server.registerTool(...) call there:

server.registerTool(
  "my_tool",
  { description: "What this tool does." },
  async (extra) => {
    const authInfo = (extra as { authInfo?: AuthInfo } | undefined)?.authInfo;
    const userId = (authInfo?.extra as { sub?: unknown } | undefined)?.sub;
    // ... your tool logic, using userId or authInfo.scopes as needed ...
    return { content: [{ type: "text", text: JSON.stringify({ result: "..." }) }] };
  },
);

The authInfo object is the already-verified caller identity — authInfo.extra.sub is the Auth0 user ID, authInfo.scopes is the token's granted scopes, authInfo.clientId is the calling application. Only sub is guaranteed present on every access token; other OIDC claims (name, email, etc.) are ID token claims and won't appear here unless a Post-Login Action explicitly copies them into the access token.

If a tool needs to call the Auth0 Management API (beyond what the setup flow already does), add the required scope to auth0.scopes in both webtask.json and package.json, then follow Deploy to Auth0 below — a scopes change requires a full reinstall/update.

Deploy to Auth0

1. Perform a full Custom Extension import or update from this public repository. Do not use a code-only redeploy when the manifest changes.

2. Open the installed extension and select Sign in and provision.

3. Complete the Dashboard-admin login. The extension creates or reuses an RS256 Auth0 API resource server whose identifier is the displayed MCP URL, a client grant on that resource server authorizing third-party clients (default_for: "third_party_clients", allow_all_scopes: true), and corrects the tenant's resource_parameter_profile to "compatibility" if needed.

4. Import https://github.com/mustafadeel/auth0-ext-wellknown as a separate Custom Extension in the same tenant. Keep its name .well-known and useHashName: false. It requires no configuration — it derives the MCP resource URL and tenant issuer from each request automatically.

5. On the same setup page, promote a connection to domain-level if none is promoted yet. Third-party and dynamically registered MCP clients can only authenticate through a domain-level connection.

6. Register the MCP client: if Dynamic Client Registration or Client ID Metadata Document support is enabled for the tenant most clients register themselves; the setup page has a button to enable either directly if it isn't already. Otherwise follow the manual application setup shown on the setup page.

7. Connect Claude, Codex, or MCP Inspector to the displayed /mcp URL and complete OAuth.

The public MCP, health, meta, and metadata routes never change tenant configuration. Only the Dashboard-admin-protected setup routes can provision the resource server and list/promote connections. GET /meta serves webtask.json's contents verbatim and is unauthenticated by design, matching the equivalent route in other Auth0 extensions.

Optional external public endpoint

The default audience is the installed Webtask URL plus /mcp. If you intentionally put an external proxy or custom domain in front of the MCP server, add an optional PUBLIC_BASE_URL setting to webtask.json and set it to the proxy origin. The resource-server identifier becomes ${PUBLIC_BASE_URL}/mcp.

Local checks

npm install
npm test

The smoke test invokes the compiled bundle directly with a simulated Webtask request, verifying the landing page, /meta, and the admin-login route are present, and that every setup-admin route rejects unauthenticated requests. The build step additionally validates the packaged dist/package.json against Auth0's real extension schema.