Authorization with Auth0

Example: Auth0

This guide uses Auth0 as the Identity Provider.

Pre-requisites

1. Create an Apollo account.

2. Clone the repo for the example project.

   sh

   copy

   git clone git@github.com:apollographql/apollo-mcp-server.git

3. Install or update the Rover CLI. You need at least v0.35 or later.

   sh

   copy

   curl -sSL https://rover.apollo.dev/nix/latest | sh

Step 1: Set up the Auth0 Identity Provider

Create an Auth0 account.

Create the Auth0 API

1. In your dashboard, navigate to Applications -> APIs.

2. Click Create API.

3. Give it a friendly name like MCP Auth API.

4. For the Identifier field, Auth0 recommends using a URL. This identifier is used in the MCP server configuration later as the audience property. For this guide, use http://localhost:8000/mcp-example.

5. Leave the defaults for the rest of the fields and click Create.

6. Navigate to your dashboard Settings.

   1. Under General -> API Authorization Settings, set the Default Audience to the Identifier you chose.

   2. Navigate to the Advanced tab.

   3. Toggle on Dynamic Client Registration (DCR) to enable dynamic client registration.

   4. Toggle on Enable Application Connections.

   5. Save your changes.

Create the Auth0 Connection

The Auth0 Connection is the method clients use to authenticate. This guide uses the default Username-Password-Authentication connection.

1. In your Auth0 dashboard, navigate to Authentication -> Database.

2. Create the default Username-Password-Authentication connection. Click the Try Connection button to test it and set up a username and password for later.

3. Back on your Auth0 dashboard, note the Connection Identifier at the top of the page. It should start with something like con_. Copy it into a temporary location. This guide refers to it as <CONNECTION ID>.

4. Navigate to Applications -> APIs -> Auth0 Management API.

5. Copy the Identifier for the Auth0 Management API to a temporary location. It should look something like dev-123456.us.auth0.com, where dev-123456 is your Auth0 tenant ID. This guide refers to it as <AUTH0 DOMAIN>.

6. Click the API Explorer tab. Copy the token value to a temporary location. This guide refers to it as <MGMT API ACCESS TOKEN>.

7. Run the following curl command to promote the connection to domain level, replacing <CONNECTION ID>, <AUTH0 DOMAIN>, and <MGMT API ACCESS TOKEN> with the values you copied in the previous steps:

   sh

   copy

   1curl --request PATCH \
   2  --url 'https://<AUTH0 DOMAIN>/api/v2/connections/<CONNECTION ID>' \
   3  --header 'authorization: Bearer <MGMT API ACCESS TOKEN>' \
   4  --header 'cache-control: no-cache' \
   5  --header 'content-type: application/json' \
   6  --data '{ "is_domain_connection": true }'

Your Auth0 setup is now complete. You have an API with an audience and a connection for authentication.

Step 2: Configure the MCP Server for authorization

Configure the MCP server to use the Auth0 instance for authentication.

1. Open the example repo you cloned earlier.

2. In the graphql/TheSpaceDevs directory, open the config.yaml file.

3. Add the following auth configuration under the transport key:

   YAML

   graphql/TheSpaceDevs/config.yaml

   copy

   1transport:
   2  type: streamable_http
   3
   4  auth:
   5    servers:
   6      - https://<AUTH0 DOMAIN> # Fill in your Auth0 domain
   7    audiences:
   8      - <AUTH0 DEFAULT AUDIENCE> # Fill in your Auth0 Identifier
   9    resource: http://127.0.0.1:8000/mcp
   10    scopes:
   11      - read:users # Adjust scopes as needed

4. Replace the <AUTH0 DOMAIN> with your own Auth0 domain from earlier.

5. Replace the <AUTH0 DEFAULT AUDIENCE> with the matching Identifier you set when creating the Auth0 API. In this guide, you used http://localhost:8000/mcp-example.

Your MCP server is now configured to use Auth0 for authentication.

Step 3: Configure the router for JWT authentication

Configure your GraphOS Router to validate JWTs issued by Auth0. This involves setting up the JWKS endpoint and defining the authorization rules.

Define authorization and authentication rules in the router

1. In the graphql/TheSpaceDevs directory, create a new file called router.yaml.

2. Paste the following configuration, replacing <AUTH0 DOMAIN> with your Auth0 domain:

   YAML

   graphql/TheSpaceDevs/router.yaml

   copy

   1authorization:
   2  require_authentication: true # Enforces authentication on all requests
   3authentication:
   4  router:
   5    jwt:
   6      jwks:
   7        - url: https://<AUTH0 DOMAIN>/.well-known/jwks.json
   8homepage:
   9  enabled: false
   10sandbox:
   11  enabled: true
   12supergraph:
   13  introspection: true

   With this configuration, the router requires authentication for all requests. If a request doesn't include an Authorization token, the router returns an UNAUTHENTICATED error.

Retrieve your GraphOS license credentials for auth

You need a graph's credentials and a valid GraphOS plan to use the router's authentication features.

1. Navigate to GraphOS Studio and log in.

2. Click Add graph and Connect an existing graph.

3. Give it a name and click Next.

4. In the next modal, find the command that looks something like this:

   sh

   copy

   APOLLO_KEY=<YOUR_APOLLO_KEY> \
   rover subgraph publish <YOUR_APOLLO_GRAPH_REF> \
   --schema ./products-schema.graphql \
   --name your-subgraph-name \
   --routing-url http://products.prod.svc.cluster.local:4001/graphql

   Note: You don't need to run this command.

5. Retrieve the values for YOUR_APOLLO_KEY and YOUR_APOLLO_GRAPH_REF from the modal and click Finish later.

Run the MCP Server and router

1. Back in your terminal, in the root of the project directory, replace and run the following command to start the MCP Server and the router together:

   sh

   copy

   1APOLLO_GRAPH_REF=<YOUR_APOLLO_GRAPH_REF> APOLLO_KEY=<YOUR_APOLLO_KEY> \
   2rover dev --supergraph-config ./graphql/TheSpaceDevs/supergraph.yaml \
   3--router-config ./graphql/TheSpaceDevs/router.yaml \
   4--mcp ./graphql/TheSpaceDevs/config.yaml

2. Test the router by navigating to http://localhost:4000 in your browser. You should see the Explorer, where you can run GraphQL queries against the router.

3. Remember, the router is configured to require authentication on all requests. Any operations without a valid Authorization token returns an UNAUTHENTICATED error. Run the operation:

   GraphQL

   copy

   1query GetAstronautsCurrentlyInSpace {
   2  astronauts(filters: { inSpace: true, search: "" }) {
   3    results {
   4      id
   5      name
   6      timeInSpace
   7      lastFlight
   8    }
   9  }
   10}

4. You should see an UNAUTHENTICATED error, which means the router is correctly enforcing authentication.

Step 4: Make requests with MCP Inspector

1. In a new terminal window, run the MCP Inspector:

   sh

   copy

   1npx @modelcontextprotocol/inspector

   The browser should open automatically with a proxy auth token.

2. In the MCP Inspector, select Streamable HTTP as the Transport Type and enter http://127.0.0.1:8000/mcp as the URL.

3. Click Connect. This triggers the OAuth flow, and you are redirected to the Auth0 login page.

4. Log in with the credentials you set up in the Auth0 connection and allow MCP Inspector access.

5. After you connect, the browser redirects back to MCP Inspector.

6. Click List Tools to see the available tools.

7. Select the GetAstronautsCurrentlyInSpace tool listed and click Run Tool.

8. You should see the results of the query, which means the authentication is working correctly.

You can select the Auth tab in MCP Inspector to see the details of the authenticated user and the scopes granted.

Step 5: Make requests with an MCP Client (Goose)

We'll use Goose as our MCP Client. Goose allows you to choose between many different LLMs and provides some built-in functionality for connecting to MCP servers, called Extensions.

Install the Goose CLI, following the instructions for your operating system. Set up the LLM provider of your choice with goose configure --> Configure Providers. Each provider has its own set of instructions, rate limiting and pricing.

Then, continue with the following steps:

1. In your terminal, run goose configure.

2. Select or enter the following answers at the prompts:

1. To start Goose, type goose. This will open a browser window and send you through the auth flow.

2. Log in to your Auth0 instance and authorize your MCP server to gain access to your tools.

3. In Goose, ask "What astronauts are in space right now?". This question is similar to the GetAstronautsCurrentlyInSpace operation from earlier, which fails as unauthenticated without the proper token.

4. Goose will select the GetAstronautsCurrentlyInSpace tool and respond with information about the astronauts found in TheSpaceDevs.

Troubleshooting

Common Issues

MCP Server Won't Start

• Error: "Port 8000 is already in use"

  • Solution: Kill any existing processes using port 8000 or specify a different port with the transport.port option or APOLLO_MCP_TRANSPORT__PORT env variable

• Error: "Failed to load supergraph configuration"

  • Solution: Verify you're running the command from the repo root directory

  • Solution: Check that the path to supergraph.yaml is correct

• Error: "License violation"

  • Solution: Ensure that the rover dev command includes valid APOLLO_KEY and APOLLO_GRAPH_REF values and that your plan supports authentication features.

• Error: "What URL is your subgraph running on?" question in terminal

  • Solution: Verify that the file path for your config files is correct. You should run the rover dev command from the root of the example project directory and the file paths should be relative to that root.

MCP Inspector Connection Issues

• Error: "Failed to connect to server"

  • Solution: Ensure the MCP server is running (check terminal output)

  • Solution: Verify you're using the correct URL (http://127.0.0.1:8000/mcp)

  • Solution: Check if your firewall is blocking the connection

Infinite loop during OAuth flow

• Issue: After logging in to Auth0, MCP Inspector keeps refreshing and doesn't complete the OAuth flow

  • Solution: In MCP Inspector, open the Authentication panel in the sidebar. Clear out any values in the Header Name and Bearer Token fields. Then try connecting again.

  • Solution: In MCP Inspector, select Clear OAuth State and try connecting again.

Getting Help

If you're still having issues:

1. Check the Apollo MCP Server GitHub issues.

2. Join the Apollo Community MCP Server Category.

3. Contact your Apollo representative for direct support.