Copy page

Guides

Setting up Auth0 as an Authentication Server for MCP OAuth Authentication

In this guide, you'll learn how to configure Auth0 as an Authorization Server for use with the MCP Server handler. See the MCP Server Handler docs for instructions on how to configure your Zuplo gateway to support OAuth authentication for your MCP Server.

This guide will assume that you already have a working Auth0 account and tenant.

Create an Auth0 API

First, you will need to create an Auth0 API. This API will be used to represent your MCP Server.

1. In the Auth0 dashboard, navigate to the Applications > APIs section and click Create API.
2. Set the Name to something like "MCP Server" and the Identifier to the canonical URL of your MCP Server. For example, if your MCP Server is hosted at https://my-gateway.zuplo.dev/mcp, then the identifier would be https://my-gateway.zuplo.dev/mcp. The trailing slash isn't required.
3. Leave the Signing Algorithm as RS256 and click Create.

Configure the Connection

Next, you will need to configure an Auth0 Connection for your API.

1. Click the Authentication tab in the left hand sidebar.

2. Click the type of Authentication connection you would like to use. For this tutorial, we will use the default Database Username-Password-Authentication connection. If you aren't using the default database connection, then create a new connection of the type you want to use and configure it with your desired settings. Click the Try Connection button to make sure that it's working. Note the Identifier of the connection. You will need this in one of the next steps.

3. Promote the connection that you would like to use for your MCP Client authentication to be a domain level connection. To do this, you will need to use the Auth0 management API. You will need to create an Auth0 Management API token with the update:connections scope. You can obtain one by following this Auth0 doc.

4. Follow the Promote Connections to Domain Level Auth0 doc to promote your connection to a domain level connection. You will need the connection ID from step 2, as well as the Auth0 Management API token from step 3.

   For example using curl:

   Code
   curl --request PATCH \
   --url 'https://your-auth0-domain.us.auth0.com/api/v2/connections/CONNECTION_ID' \
   --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
   --header 'cache-control: no-cache' \
   --header 'content-type: application/json' \
   --data '{ "is_domain_connection": true }'

5. Enable Resource Parameter Compatibility Profile. See the Auth0 tenant settings docs for more information.

After completing these changes to your Auth0 tenant, you will need to enable CIMD or DCR (or both) on your Auth0 tenant.

Enable CIMD for MCP OAuth

To use CIMD for MCP OAuth authentication, do the following:

1. In the Auth0 dashboard, navigate to the tenant settings in Settings on the left hand sidebar.
2. Navigate to the Advanced tab.
3. Scroll down to the Settings section and check the toggle for Client ID Metadata Document (CIMD) Registration.
4. Register the MCP clients via their public CIMD client data metadata URL by clicking "Create Application" and then "Import from URL". Note that for all the MCP clients you want to support, you will need to obtain the metadata URL and register each application individually.

See the official Auth0 docs for more information.

Enabling DCR for MCP OAuth

To use DCR for MCP OAuth authentication, do the following:

1. In the Auth0 dashboard, navigate to the tenant settings in Settings on the left hand sidebar.
2. Navigate to the Advanced tab.
3. Scroll down to the Settings section and check the toggle for Dynamic Client Registration (DCR). Also ensure that the Enable Application Connections toggle is checked.

See the official Auth0 docs for more information.

Configure OAuth on Zuplo

To set up your gateway to support OAuth authentication for your MCP Server, you will need to do the following:

1. Create an OAuth policy on your MCP Server route. This policy will need to have the option "oAuthResourceMetadataEnabled": true, for example:

   Code
   {
     "name": "mcp-oauth-inbound",
     "policyType": "oauth-inbound",
     "handler": {
       "export": "Auth0JwtInboundPolicy",
       "module": "$import(@zuplo/runtime)",
       "options": {
         "auth0Domain": "my-auth0-domain.us.auth0.com",
         "audience": "https://my-mcp-audience",
         "oAuthResourceMetadataEnabled": true
       }
     }
   }

2. Add the OAuth policy to the MCP Server route. For example:

   Code
   "paths": {
     "/mcp": {
       "post": {
         "x-zuplo-route": {
           // etc. etc.
           // other properties and route handlers for MCP
   
           "policies": {
             "inbound": [
               "mcp-oauth-inbound"
             ]
           }
         }
       }
     }
   }

3. Add the OAuthProtectedResourcePlugin to your runtimeInit function in the zuplo.runtime.ts file:

   Code
   import {
     RuntimeExtensions,
     OAuthProtectedResourcePlugin,
   } from "@zuplo/runtime";
   
   export function runtimeInit(runtime: RuntimeExtensions) {
     runtime.addPlugin(
       new OAuthProtectedResourcePlugin({
         authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
         resourceName: "My MCP OAuth Resource",
       }),
     );
   }

   See the OAuth Protected Resource Plugin docs for more details.

See the MCP Server Handler docs for more details.

Testing

Use the MCP Inspector, a developer focused tool for building MCP servers, to quickly and easily test out your MCP server:

Code
npx @modelcontextprotocol/inspector

To connect to your remote Zuplo MCP server in the Inspector UI:

1. Set the Transport Type to "Streamable HTTP"
2. Set the URL to your Zuplo gateway with the route used by the MCP Server Handler (that is, https://my-gateway.zuplo.dev/mcp)
3. You will need to login using the OAuth flow using the Open Auth Settings button.
4. Hit Connect.

For debugging your OAuth configuration, hit the Open Auth Settings button in the Inspector UI to start the OAuth flow. When first setting up the OAuth flow, it's recommmended to use the Guided OAuth Flow which you will see when you open the OAuth settings. This will allow you to debug the flow step by step.

You should be able to hit the Continue button in the Inspector UI at each step of the flow successfully. If you need more help debugging, see Testing OAuth on Zuplo.