Add MCP Server example #2299

patrickkang · 2025-09-02T19:11:28Z

All new/changed/fixed functionality is covered by tests (or N/A)
I have added documentation for all new/changed functionality (or N/A)

📋 Changes

Adds MCP Server example with Auth0 integration

📎 References

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

🎯 Testing

Use a MCP client like MCP inspector to test your MCP server

codecov-commenter · 2025-09-02T19:12:18Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.47%. Comparing base (59f79bc) to head (06e9dea).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2299   +/-   ##
=======================================
  Coverage   85.47%   85.47%           
=======================================
  Files          26       26           
  Lines        2636     2636           
  Branches      486      486           
=======================================
  Hits         2253     2253           
  Misses        377      377           
  Partials        6        6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

josh-cain · 2025-09-04T13:25:21Z

examples/mcp/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.


Can we review to see what's actually needed here? Most of this is already covered in the root .gitignore.

Cleaned up in 22d9446

josh-cain · 2025-09-04T13:30:27Z

examples/mcp/README.md

+
+## Auth0 Tenant Setup
+
+For detailed instructions on setting up your Auth0 tenant for MCP server integration, please refer to the [Auth0 Tenant Setup guide](https://github.com/auth0/auth0-auth-js/blob/main/examples/example-fastmcp-mcp/README.md#auth0-tenant-setup).


This link 404s

This link should be available once auth0/auth0-auth-js#45 merges in

This is resolved now that the above PR is merged in

josh-cain · 2025-09-04T13:34:10Z

examples/mcp/README.md

+With the configuration in place, the example can be started by running:
+
+```bash
+npm run start


Why npm since we're using pnpm for build? Also why start? Probably need to either:

Include a run build step so start works (fails currently w/out it)

Or use run dev instead

addressed in 5882a9f

josh-cain · 2025-09-04T13:38:24Z

examples/mcp/pnpm-lock.yaml

+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:


Shouldn't we just have the one root pnpm-lock.yaml file? Why is this here?

I am following the pattern used in other examples: https://github.com/search?q=repo%3Aauth0%2Fnextjs-auth0%20pnpm-lock.yaml&type=code and

nextjs-auth0/package.json

Line 13 in fe1f5e7

"install:examples": "pnpm install --filter ./examples/with-next-intl --shamefully-hoist && pnpm install --filter ./examples/with-shadcn --shamefully-hoist",

Not too sure on the reason here though. I will check in with the sdk team to confirm

https://auth0team.atlassian.net/browse/ESD-51351

Confirmed with the sdk team. The examples here are meant to be standalone next applications https://auth0team.atlassian.net/browse/ESD-51351?focusedCommentId=1019127

gyaneshgouraw-okta · 2025-10-06T12:40:06Z

@claude

github-actions · 2025-10-06T12:40:33Z

Claude encountered an error —— View job

Failed with exit code 128

I'll analyze this and get back to you.

gyaneshgouraw-okta · 2025-10-06T14:51:42Z

Hi @patrickkang, thank you for sharing this example! I noticed that it doesn’t appear to use nextjs-auth0. Could you help me understand the rationale for including it in the Next.js SDK repository?

gyaneshgouraw-okta · 2025-10-06T14:13:00Z

examples/mcp/src/auth0.ts

+        clientId,
+        scopes:
+          typeof decoded.scope === "string"
+            ? decoded.scope.split(" ").filter(Boolean)


Can we simplify this return block? I notice it contains ternary conditions, claims checks, and other logic all within the return statement, which makes the code a bit hard to follow and less intuitive.

I agree, but i think this can be addressed in a separate PR unless this is a real blocker. We also have other MCP examples that follows this

gyaneshgouraw-okta · 2025-10-06T14:43:08Z

examples/mcp/src/auth0.ts

+
+interface Auth0Mcp {
+  verifyToken: ReturnType<typeof createTokenVerifier>;
+  requireScopes: ReturnType<typeof createScopeValidator>;


Hi @patrickkang, just to clarify, does this example mainly aim to demonstrate how users can implement custom logic for token verification and scope validation, or does it also illustrate how to obtain a token?

It is mainly to demonstrate token verification, user identity extraction, and protected MCP tools(scope based access control)

gyaneshgouraw-okta · 2025-10-06T14:45:29Z

examples/mcp/package.json

+  },
+  "dependencies": {
+    "@auth0/auth0-api-js": "^1.0.2",
+    "@auth0/nextjs-auth0": "^4.5.1",


I don't see @auth0/nextjs-auth0 used in this example, am i missing anything ?

My mistake - this example does not depend on nextjs-auth0

gyaneshgouraw-okta · 2025-10-06T14:48:24Z

examples/mcp/README.md

+# Example Nextjs MCP Server with Auth0 Integration
+
+This is a practical example of securing a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs) server
+with Auth0.


I feel it might be helpful to include a bit more detail on how the application is being secured, particularly highlighting the key aspects of the security implementation.

We are working on additional docs and blogs to highlight this better

patrickkang · 2025-10-08T15:20:40Z

Closing this in favour of auth0/auth0-auth-js#70

patrickkang marked this pull request as ready for review September 2, 2025 20:03

patrickkang requested a review from a team as a code owner September 2, 2025 20:03

josh-cain reviewed Sep 4, 2025

View reviewed changes

patrickkang added 7 commits September 16, 2025 09:48

add mcp example

0398cb5

add some more types

a7a9ef7

clean up

546e8fa

mark as beta

e85c315

simplify the mcp example gitignore

9e07ae4

update README to update running the server commands

96366f2

more cleanup

06e9dea

patrickkang force-pushed the add-mcp-example branch from c57c987 to 06e9dea Compare September 16, 2025 13:48

gyaneshgouraw-okta reviewed Oct 6, 2025

View reviewed changes

patrickkang closed this Oct 8, 2025

		@@ -0,0 +1,41 @@
		# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.


		## Auth0 Tenant Setup

		For detailed instructions on setting up your Auth0 tenant for MCP server integration, please refer to the [Auth0 Tenant Setup guide](https://github.com/auth0/auth0-auth-js/blob/main/examples/example-fastmcp-mcp/README.md#auth0-tenant-setup).

Add MCP Server example #2299

Add MCP Server example #2299

Uh oh!

Conversation

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

Uh oh!

📋 Changes

📎 References

🎯 Testing

Uh oh!

codecov-commenter commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

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!

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!

gyaneshgouraw-okta commented Oct 6, 2025

Uh oh!

github-actions bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gyaneshgouraw-okta commented Oct 6, 2025

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!

Choose a reason for hiding this comment

Uh oh!

patrickkang commented Oct 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

patrickkang commented Sep 2, 2025 •

edited

Loading

codecov-commenter commented Sep 2, 2025 •

edited

Loading

github-actions bot commented Oct 6, 2025 •

edited

Loading