MCP Workshop

A hands-on workshop that builds an MCP server with xmcp and secures it with Auth0 for MCP. You start with an open server that has two tools (whoami and order_pizza), then add Auth0 authentication, register the MCP client with a Client ID Metadata Document (CIMD), and finally restrict each tool with per-tool permissions assigned through Auth0 roles.

Each step of the workshop is a git branch, and every code change and Auth0 setting is documented in the guide/ folder.

Related content

• Auth0 for MCP: how Auth0 authenticates and authorizes MCP clients.
• Register your MCP client application: Dynamic Client Registration and CIMD in Auth0.
• xmcp Auth0 integration: the @xmcp-dev/auth0 plugin used in this workshop.
• MCP Inspector: the client used to test the server.

Steps

Step	Branch	What you get
1	step-1-start-state	Barebones xmcp server with two tools: whoami and order_pizza
2	step-2-add-auth	The server is protected by Auth0 and both tools know who is calling
3	step-3-add-client	A client/ folder that serves the Client ID Metadata Document (CIMD)
4	step-4-tool-permissions	Each tool call is checked against a per-tool permission

Each branch builds on the previous one. main is the same as step-1-start-state. The guide/ folder is identical on every branch.

Requirements

• Node.js 22 or later (22.19 or later for the MCP Inspector) and npm
• git
• An Auth0 account and tenant (from step 2)
• The Auth0 CLI and jq (optional, every Auth0 step also has a Dashboard route)
• cloudflared or ngrok to expose the CIMD file (from step 3)

Step 1 only needs Node.js and git.

Download and run

Clone the repository and start from the first step:

git clone https://github.com/atko-cic-devrel/mcp-workshop.git
cd mcp-workshop
git checkout step-1-start-state

Install and start the server:

cd server
npm install
npm run dev

The MCP endpoint is now available at http://localhost:3001/mcp. In another terminal, connect with the MCP Inspector:

npx @modelcontextprotocol/inspector --server-url http://localhost:3001/mcp --transport http

Open the URL the command prints (it contains a one-time session token), connect to the server on the Servers tab, then call whoami or order_pizza from the Tools tab.

To move on, check out the next branch and follow its guide:

git checkout step-2-add-auth

Steps 2 to 4 need an Auth0 tenant. Create a server/.env from server/.env.example and fill in the values as described in the step 2 guide. Run npm install in server/ after switching branches, because the dependencies change in step 2. Step 3 adds the client/ folder, which you start with cd client && npm start.

Guide

Follow the steps in order:

0. Prerequisites and tooling
1. Start state
2. Add Auth0 authentication
3. Add the client and CIMD file
4. Per-tool permissions

License

Copyright 2026 Okta, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

See LICENSE.txt for the full license text and NOTICE.txt for the licenses of the third-party dependencies.