Authorization with Apollo MCP Server

The Apollo MCP server supports authorizing clients (e.g., LLMs) in accordance with the MCP specification.

Implement authorization with Apollo MCP Server

To implement authorization, you need an OAuth 2.1-compliant Identity Provider (for example, your own in-house IdP or a third-party IdP such as Auth0, Okta, or Keycloak). You need the following values from your IdP:

• URL: The base URL of your Identity Provider, which is used to validate the JSON Web Tokens (JWTs) issued by it.

• Audience: Identifies the intended recipient of the token, typically a resource server or API. Represented by the aud claim in the JWT.

• Scopes: The scopes that the client will request. These scopes define the permissions granted to the client when it accesses the API.

Then, you configure the MCP server with auth settings and the GraphOS Router for JWT authentication using those IdP values.

Example: Auth0

This guide uses Auth0 as the Identity Provider.

Pre-requisites

1. Create an Apollo account.

   PLAN REQUIRED

   This feature is available on the following GraphOS plans: Developer, Standard, Enterprise.

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/download/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:5000/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 OIDC Dynamic Application Registration 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 dashboard, navigate to Authentication -> Database.

2. Create the default Username-Password-Authentication connection. Click the Try Connection button to test it.

3. Copy the Connection Identifier at the top of the page, you need it for the next step. It should start with something like con_.

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

5. Click the API Explorer tab. Copy the token value, you also need it for the next step.

6. Run the following curl command to promote the connection to domain-level, replacing CONNECTION_ID and MGMT_API_ACCESS_TOKEN with the values you copied in the previous steps:

   sh

   copy

   1curl --request PATCH \
   2  --url 'https://dev-p7nxaluy3f2ss4js.us.auth0.com/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:5000/mcp
   10    scopes:
   11      - read:users # Adjust scopes as needed

4. Replace the <AUTH0 DOMAIN> with your own Auth0 domain. It should look something like dev-123456.us.auth0.com, where dev-123456 is your Auth0 tenant ID.

5. Replace the <AUTH0 DEFAULT AUDIENCE> with the matching Identifier you set when creating the Auth0 API. In this guide, you used http://localhost:5000/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.

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:5000/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.

Troubleshooting

Common Issues

MCP Server Won't Start

• Error: "Port 5000 is already in use"

  • Solution: Kill any existing processes using port 5000 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:5000/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.