feat(example): Add FastMCP MCP server example by patrickkang · Pull Request #45 · auth0/auth0-auth-js

patrickkang · 2025-08-18T13:50:02Z

Description

This PR adds FastMCP MCP server example with Auth0 integration

References

https://auth0team.atlassian.net/browse/AIDX-114

Testing

Follow README.md#Auth0 Tenant Setup
to set up your auth0 tenant and use a MCP client like MCP inspector to test your MCP server.

This change adds test coverage for new/changed/fixed functionality

Checklist

I have added documentation for new/changed functionality in this PR or in auth0.com/docs
All active GitHub checks for tests, formatting, and security are passing
The correct base branch is being used, if not the default branch

frederikprijck · 2025-08-18T16:42:15Z

+
+This guide uses [Auth0 CLI](https://auth0.github.io/auth0-cli/) to configure an Auth0 tenant for secure MCP tool access.
+
+### Step 1: Authenticate with Auth0 CLI


Should we add installing the Auth0 CLI as a dependency? Or is this example usable without installing it?

You can configure your tenant from the dashboard or with the Management API. The Auth0 CLI isn't required, but it simplifies the setup process.

But the entire next steps rely on the auth0 CLI, which makes it a required prerequisite to follow any of the following steps.

👍 That makes sense. I updated it to explicitly say that auth0 cli is a prerequisite to follow the rest of steps

Perhaps, we can add a small sentence that explains everything can be configured through the manage dashboard as well if prefered.

frederikprijck · 2025-08-18T16:55:42Z

+2. Set the Default Audience: This ensures that users logging in interactively get access tokens that are valid for your
+   newly created MCP API. Replace `http://localhost:3001` with the same API identifier you used above.


Is there a reason why we do this in the context of MCP? Isn't this something that would work for any audience in any context? This just ensures that, when no audience is send along with authorize, this audience is used. Setting this as a default audience has consequences on existing clients and auth flows without audience.

We are resorting to using default audience until we get the resource parameter support out.

More details here:
https://auth0.slack.com/archives/C091X0B50MA/p1753471387446879?thread_ts=1753459734.480379&cid=C091X0B50MA
and
https://oktawiki.atlassian.net/wiki/spaces/AFG1/pages/3666641175/RFD+resource+parameter?focusedCommentId=3669787109

We can explicitly call out that setting the default audience is a tenant-wide config change and that it affects all auth flows. WDYT?

I think it might make sense to add a comment to this paragraph that indicates that this step is temporary until we have proper support for Resource Indicators for OAuth 2.0 as defined in RFC 8707. It is not an optional step, because if you skip it today, the issued AT will not be scoped specifically to the RS.
Good news is that support for RFC 8707 is coming very soon and we can tweak the instructions here to instead set the resource_parameter_profile to "compatibility".

addressed in 5643498

frederikprijck · 2025-08-18T17:57:12Z

+/**
+ * Wrapper for FastMCP tools that requires specific OAuth 2.0 scopes.
+ */
+export function requireScopes<T, R>(


Is enforcing scopes expected? In other examples, we use requireAuth with an optional scope parameter. I think typically, we want scopes to be used, but should it also be usable without scopes?

For the tools that do not need specific tool scope enforcement, you'd pass the tool handler directly without the requireScopes wrapper.

pmalouin

still not finished reviewing, but queueing up a few early comments

pmalouin · 2025-08-25T21:05:50Z

+2. Set the Default Audience: This ensures that users logging in interactively get access tokens that are valid for your
+   newly created MCP API. Replace `http://localhost:3001` with the same API identifier you used above.


I think it might make sense to add a comment to this paragraph that indicates that this step is temporary until we have proper support for Resource Indicators for OAuth 2.0 as defined in RFC 8707. It is not an optional step, because if you skip it today, the issued AT will not be scoped specifically to the RS.
Good news is that support for RFC 8707 is coming very soon and we can tweak the instructions here to instead set the resource_parameter_profile to "compatibility".

pmalouin · 2025-08-25T21:25:16Z

+auth0 users roles assign "auth0|USER_ID_HERE" --roles "YOUR_ROLE_ID_HERE"
+```
+
+### Step 6: Configure and Deploy the Scope-Injection Action


Is this section absolutely needed? I just went ahead and skipped it and my AT contains the scope claim with the right value (derived from the RBAC roles + permissions defined in Step 5).
Can we double-check that this is indeed needed or perhaps isn't needed anymore?

We could leave a comment about the fact that any further customization not supported out of the box by RBAC can be done via a custom Post-Login action trigger, but I'd consider that optional.

As discussed, we are removing the post-login action from the tenant settings and keep the tenant setup simple for now.

I've added this note for optional configuration: **Note:** Further customization not supported out of the box by RBAC can be done via a custom Post-Login action trigger.

pmalouin

finished reviewing ✔️ just a couple feedback items, but this is quite neat overall 💪

pmalouin · 2025-08-26T00:33:19Z

+      readOnlyHint: true,
+    },
+    parameters: greetParameters,
+    execute: requireScopes<z.infer<typeof greetParameters>, string>(


I was reviewing the docs for FastMCP, and it looks like one idiomatic way to authorize access to individual tools based on the current auth context is to declare a canAccess(auth) field method.

So we could create a helper function like:

function hasAllScopes( requiredScopes: readonly string[] ): (auth: FastMCPAuthSession) => boolean { return (auth: FastMCPAuthSession) => { const userScopes = auth.scopes; return requiredScopes.every((scope) => userScopes.includes(scope) ); }; }

... and use it in the tool declaration like this:

{ name: "greet", description: "Greet a user with personalized authentication information from Auth0.", annotations: { title: "Greet User (FastMCP)", readOnlyHint: true, }, parameters: greetParameters, canAccess: hasAllScopes(["tool:greet"]), //<<<< .... },

This has the added benefit that the "list tools" command will filter out any tool that is not currently allowed (based on the scopes of the current AT).

Moreover, I think that this approach allows to get rid of requireScopes(), or more specifically, we don't need to wrap the tool's execute method with a scope-checking helper.

👍 Thanks for the suggestion. This simplifies a lot

pmalouin · 2025-08-26T00:40:12Z

+    // Validate required scopes
+    if (!validateScopes(decoded, MCP_TOOL_SCOPES)) {
+      throw new InsufficientScopeError(
+        `Token is missing required scopes: ${MCP_TOOL_SCOPES.join(", ")}`
+      );
+    }


I'm not sure that this makes sense if we want to allow the user to only have a subset of scopes (vs all possible scopes supported by the MCP server). If I try to authenticate with an AT that does not have all of MCP_TOOL_SCOPES, then the error is thrown and I can't even connect to the MCP server (whereas I'd expect at least to be able to access a narrower set of tools).

Moreover, the error seen on MCP Inspector is not self-explanatory so it would lead to sub-par UX:

This check was not needed there. Addressed in 420a2d0

pmalouin · 2025-08-26T01:24:31Z

+    }
+    const decoded = (await apiClient.verifyAccessToken({
+      accessToken,
+    })) as AccessTokenClaims;


Using as here could hide some inconsistencies between the actual data type of claims received via the token. I'd recommend implementing proper string guard clauses to extract the client_id, azp, scope, name and email claims. This way, you aren't doing a leap of faith from unknown to string, even though we know that auth0 will return those claims as strings.

A handy helper can be used to do the type narrowing:

function isNonEmptyString(value: unknown): value is string { return typeof value === "string" && value.length > 0; }

...which can for example simplify the block below to:

extra: { sub: decoded.sub, ...(isNonEmptyString(decoded.client_id) && { azp: decoded.client_id }), ...(isNonEmptyString(decoded.azp) && { azp: decoded.azp }), ...(isNonEmptyString(decoded.name) && { name: decoded.name }), ...(isNonEmptyString(decoded.email) && { email: decoded.email }), },

Other typescript warnings can be addressed similarly.

also related, but non-blocking, should we validate that sub is set and non-empty? (and throw if not)

👍 We should validate sub claim and added that in

Co-authored-by: Patrick Malouin <p.malouin@gmail.com>

pmalouin

just a tiny comment, otherwise LGTM 🚀

Co-authored-by: Patrick Malouin <p.malouin@gmail.com>

frederikprijck · 2025-09-02T08:20:32Z

+{
+  "name": "example-fastmcp-mcp",
+  "version": "0.1.0-beta.1",
+  "description": "FastMCP Server Example (Beta) — Example implementation of an MCP server using FastMCP framework with Auth0 authentication. This example is in beta and demonstrates secure MCP server patterns with OAuth 2.0 and JWT validation.",


What is the approach to move this out of beta post merging this example?

Good call out. We are starting with beta and might not support every framework. The idea is to first validate those mcp examples and get some feedback. Framework popularity with mcp server integration is also a factor. Curious if there's an existing path we usually follow to move examples here out of beta

No we have never realy used a beta concept with examples, as they are not released like versioned artifacts.

frederikprijck · 2025-09-02T08:25:13Z

+    /**
+     * Exposes /.well-known/oauth-authorization-server endpoint for backwards compatibility.
+     * This enables backward compatibility for clients that expect authorization server metadata
+     * to be available directly from this MCP server
+     */
+    authorizationServer: {
+      issuer: `https://${AUTH0_DOMAIN}/`,
+      authorizationEndpoint: `https://${AUTH0_DOMAIN}/authorize`,
+      tokenEndpoint: `https://${AUTH0_DOMAIN}/oauth/token`,
+      jwksUri: `https://${AUTH0_DOMAIN}/.well-known/jwks.json`,
+      responseTypesSupported: ["code"],
+      scopesSupported: ["openid", "profile", "email", ...MCP_TOOL_SCOPES],
+    },
+  },


Is this neccessary for integrating Auth0?

Not to integrate with auth0, but still needed to keep backward compatibility for the MCP server

This is still done here as well: https://github.com/modelcontextprotocol/typescript-sdk/blob/3dd074f8a25b92994e0e8cc69d3ffe9112a1f32b/src/server/auth/router.ts#L207-L208

patrickkang added 2 commits August 15, 2025 17:14

add fastmcp mcp server example

cafc41f

adds auth0 tenant setup guide

3f17c9a

patrickkang marked this pull request as ready for review August 18, 2025 14:03

frederikprijck requested changes Aug 18, 2025

View reviewed changes

patrickkang added 5 commits August 19, 2025 16:11

add missing dependency

649a3b9

update README.md

7fa9b48

update README.md

1ba65c6

update README.md

fd1524d

update README

a2ea6e4

pmalouin reviewed Aug 25, 2025

View reviewed changes

pmalouin suggested changes Aug 26, 2025

View reviewed changes

patrickkang and others added 9 commits August 26, 2025 09:34

Apply suggestions from code review

f995225

Co-authored-by: Patrick Malouin <p.malouin@gmail.com>

Update examples/example-fastmcp-mcp/README.md

adf514b

Co-authored-by: Patrick Malouin <p.malouin@gmail.com>

add a comment about the default audience

5643498

update README.md

6c1c74e

remove scope check in authenticate

420a2d0

use canAccess and remove custom wrapper

1ba67a8

remove post login actions

3914a34

more cleanup in README

91df18e

more cleaning up

83f0063

patrickkang requested review from frederikprijck and pmalouin August 27, 2025 02:12

provide sample env vars in README

beab942

pmalouin approved these changes Aug 27, 2025

View reviewed changes

Comment thread examples/example-fastmcp-mcp/README.md Outdated

Update examples/example-fastmcp-mcp/README.md

6bbb80d

Co-authored-by: Patrick Malouin <p.malouin@gmail.com>

frederikprijck reviewed Sep 2, 2025

View reviewed changes

update readme

5986213

frederikprijck previously approved these changes Sep 5, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into add-example-fastmcp-mcp

34d3592

patrickkang dismissed frederikprijck’s stale review via 34d3592 September 5, 2025 15:05

frederikprijck approved these changes Sep 5, 2025

View reviewed changes

patrickkang mentioned this pull request Sep 5, 2025

Add MCP Server example auth0/nextjs-auth0#2299

Closed

2 tasks

frederikprijck merged commit fc2158d into auth0:main Sep 8, 2025
4 checks passed


		This guide uses [Auth0 CLI](https://auth0.github.io/auth0-cli/) to configure an Auth0 tenant for secure MCP tool access.

		### Step 1: Authenticate with Auth0 CLI

		2. Set the Default Audience: This ensures that users logging in interactively get access tokens that are valid for your
		newly created MCP API. Replace `http://localhost:3001` with the same API identifier you used above.

Uh oh!

Conversation

patrickkang commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

References

Testing

Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pmalouin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pmalouin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pmalouin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

patrickkang commented Aug 18, 2025 •

edited

Loading