|
| 1 | +--- |
| 2 | +title: Authorization with Apollo MCP Server |
| 3 | +--- |
| 4 | + |
| 5 | +<PlanRequired plans={["Developer", "Standard", "Enterprise"]}/> |
| 6 | + |
| 7 | +The Apollo MCP server supports authorizing clients (e.g., LLMs) in accordance with [the MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). |
| 8 | + |
| 9 | +## Implement authorization with Apollo MCP Server |
| 10 | + |
| 11 | +To implement authorization, you need an [OAuth 2.1-compliant](https://oauth.net/2.1/) 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: |
| 12 | + |
| 13 | +- **URL**: The base URL of your Identity Provider, which is used to validate the JSON Web Tokens (JWTs) issued by it. |
| 14 | +- **Audience**: Identifies the intended recipient of the token, typically a resource server or API. Represented by the `aud` claim in the JWT. |
| 15 | +- **Scopes**: The scopes that the client will request. These scopes define the permissions granted to the client when it accesses the API. |
| 16 | + |
| 17 | +Then, you [configure the MCP server with `auth` settings](/apollo-mcp-server/command-reference#auth) and the [GraphOS Router for JWT authentication](/graphos/routing/security/jwt) using those IdP values. |
| 18 | + |
| 19 | +## Example: Auth0 |
| 20 | + |
| 21 | +This guide uses [Auth0](https://auth0.com/) as the Identity Provider. |
| 22 | + |
| 23 | +### Pre-requisites |
| 24 | + |
| 25 | +1. [Create an Apollo account](https://studio.apollographql.com/signup?referrer=docs-content). |
| 26 | + |
| 27 | + <PlanRequired plans={["Developer", "Standard", "Enterprise"]} /> |
| 28 | + |
| 29 | +1. Clone the repo for the example project. |
| 30 | + |
| 31 | + ```sh showLineNumbers=false |
| 32 | + git clone [email protected]:apollographql/apollo-mcp-server.git |
| 33 | + ``` |
| 34 | + |
| 35 | +1. Install or update the Rover CLI. You need at least v0.35 or later. |
| 36 | + |
| 37 | + ```sh showLineNumbers=false |
| 38 | + curl -sSL https://rover.apollo.dev/download/latest | sh |
| 39 | + ``` |
| 40 | + |
| 41 | +### Step 1: Set up the Auth0 Identity Provider |
| 42 | + |
| 43 | +[Create an Auth0 account](https://auth0.com/). |
| 44 | + |
| 45 | +#### Create the Auth0 API |
| 46 | + |
| 47 | +1. In your dashboard, navigate to **Applications** -> **APIs**. |
| 48 | +1. Click **Create API**. |
| 49 | +1. Give it a friendly name like `MCP Auth API`. |
| 50 | +1. 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`. |
| 51 | +1. Leave the defaults for the rest of the fields and click **Create**. |
| 52 | +1. Navigate to your dashboard **Settings**. |
| 53 | + 1. Under **General** -> **API Authorization Settings**, set the **Default Audience** to the `Identifier` you chose. |
| 54 | + 1. Navigate to the **Advanced** tab. |
| 55 | + 1. Toggle on **OIDC Dynamic Application Registration** to enable [dynamic client registration](https://auth0.com/docs/get-started/applications/dynamic-client-registration#enable-dynamic-client-registration). |
| 56 | + 1. Toggle on **Enable Application Connections**. |
| 57 | + 1. Save your changes. |
| 58 | + |
| 59 | +#### Create the Auth0 Connection |
| 60 | + |
| 61 | +The Auth0 Connection is the method clients use to authenticate. This guide uses the default **Username-Password-Authentication** connection. |
| 62 | + |
| 63 | +1. In your dashboard, navigate to **Authentication** -> **Database**. |
| 64 | +1. Create the default **Username-Password-Authentication** connection. Click the **Try Connection** button to test it. |
| 65 | +1. Copy the **Connection Identifier** at the top of the page, you need it for the next step. It should start with something like `con_`. |
| 66 | +1. Navigate to **Applications** -> **APIs** -> **Auth0 Management API**. |
| 67 | +1. Click the **API Explorer** tab. Copy the token value, you also need it for the next step. |
| 68 | +1. 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: |
| 69 | + |
| 70 | + ```sh |
| 71 | + curl --request PATCH \ |
| 72 | + --url 'https://dev-p7nxaluy3f2ss4js.us.auth0.com/api/v2/connections/CONNECTION_ID' \ |
| 73 | + --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \ |
| 74 | + --header 'cache-control: no-cache' \ |
| 75 | + --header 'content-type: application/json' \ |
| 76 | + --data '{ "is_domain_connection": true }' |
| 77 | + ``` |
| 78 | + |
| 79 | +Your Auth0 setup is now complete. You have an API with an audience and a connection for authentication. |
| 80 | + |
| 81 | +### Step 2: Configure the MCP Server for authorization |
| 82 | + |
| 83 | +Configure the MCP server to use the Auth0 instance for authentication. |
| 84 | + |
| 85 | +1. Open the example repo you cloned earlier. |
| 86 | +1. In the `graphql/TheSpaceDevs` directory, open the `config.yaml` file. |
| 87 | +1. Add the following `auth` configuration under the `transport` key: |
| 88 | + |
| 89 | + ```yaml title="graphql/TheSpaceDevs/config.yaml" |
| 90 | + transport: |
| 91 | + type: streamable_http |
| 92 | + |
| 93 | + auth: |
| 94 | + servers: |
| 95 | + - https://<AUTH0 DOMAIN> # Fill in your Auth0 domain |
| 96 | + audiences: |
| 97 | + - <AUTH0 DEFAULT AUDIENCE> # Fill in your Auth0 Identifier |
| 98 | + resource: http://127.0.0.1:5000/mcp |
| 99 | + scopes: |
| 100 | + - read:users # Adjust scopes as needed |
| 101 | + ``` |
| 102 | +
|
| 103 | +1. 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. |
| 104 | + |
| 105 | +1. 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`. |
| 106 | + |
| 107 | +Your MCP server is now configured to use Auth0 for authentication. |
| 108 | + |
| 109 | +### Step 3: Configure the router for JWT authentication |
| 110 | + |
| 111 | +Configure your GraphOS Router to validate JWTs issued by Auth0. This involves setting up the JWKS endpoint and defining the authorization rules. |
| 112 | + |
| 113 | +#### Define authorization and authentication rules in the router |
| 114 | + |
| 115 | +1. In the `graphql/TheSpaceDevs` directory, create a new file called `router.yaml`. |
| 116 | +1. Paste the following configuration, replacing `<AUTH0 DOMAIN>` with your Auth0 domain: |
| 117 | + |
| 118 | + ```yaml title="graphql/TheSpaceDevs/router.yaml" |
| 119 | + authorization: |
| 120 | + require_authentication: true # Enforces authentication on all requests |
| 121 | + authentication: |
| 122 | + router: |
| 123 | + jwt: |
| 124 | + jwks: |
| 125 | + - url: https://<AUTH0 DOMAIN>/.well-known/jwks.json |
| 126 | + homepage: |
| 127 | + enabled: false |
| 128 | + sandbox: |
| 129 | + enabled: true |
| 130 | + supergraph: |
| 131 | + introspection: true |
| 132 | + ``` |
| 133 | + |
| 134 | + 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. |
| 135 | + |
| 136 | +#### Retrieve your GraphOS license credentials for auth |
| 137 | + |
| 138 | +You need a graph's credentials and a valid GraphOS plan to use the router's authentication features. |
| 139 | + |
| 140 | +1. Navigate to [GraphOS Studio](https://studio.apollographql.com/) and log in. |
| 141 | +1. Click **Add graph** and **Connect an existing graph**. |
| 142 | +1. Give it a name and click **Next**. |
| 143 | +1. In the next modal, find the command that looks something like this: |
| 144 | + |
| 145 | + ```sh showLineNumbers=false {2} |
| 146 | + APOLLO_KEY=<YOUR_APOLLO_KEY> \ |
| 147 | + rover subgraph publish <YOUR_APOLLO_GRAPH_REF> \ |
| 148 | + --schema ./products-schema.graphql \ |
| 149 | + --name your-subgraph-name \ |
| 150 | + --routing-url http://products.prod.svc.cluster.local:4001/graphql |
| 151 | + ``` |
| 152 | + |
| 153 | + Note: You don't need to run this command. |
| 154 | + |
| 155 | +1. Retrieve the values for `YOUR_APOLLO_KEY` and `YOUR_APOLLO_GRAPH_REF`. |
| 156 | + |
| 157 | +#### Run the MCP Server and router |
| 158 | + |
| 159 | +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: |
| 160 | + |
| 161 | + ```sh |
| 162 | + APOLLO_GRAPH_REF=<YOUR_APOLLO_GRAPH_REF> APOLLO_KEY=<YOUR_APOLLO_KEY> \ |
| 163 | + rover dev --supergraph-config ./graphql/TheSpaceDevs/supergraph.yaml \ |
| 164 | + --router-config ./graphql/TheSpaceDevs/router.yaml \ |
| 165 | + --mcp ./graphql/TheSpaceDevs/config.yaml |
| 166 | + ``` |
| 167 | + |
| 168 | +1. 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. |
| 169 | + |
| 170 | +1. 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: |
| 171 | + |
| 172 | + ```graphql |
| 173 | + query GetAstronautsCurrentlyInSpace { |
| 174 | + astronauts(filters: { inSpace: true, search: "" }) { |
| 175 | + results { |
| 176 | + id |
| 177 | + name |
| 178 | + timeInSpace |
| 179 | + lastFlight |
| 180 | + } |
| 181 | + } |
| 182 | + } |
| 183 | + ``` |
| 184 | + |
| 185 | +1. You should see an `UNAUTHENTICATED` error, which means the router is correctly enforcing authentication. |
| 186 | + |
| 187 | +### Step 4: Make requests with MCP Inspector |
| 188 | + |
| 189 | +1. In a new terminal window, run the MCP Inspector: |
| 190 | + |
| 191 | + ```sh |
| 192 | + npx @modelcontextprotocol/inspector |
| 193 | + ``` |
| 194 | + |
| 195 | + The browser should open automatically with a proxy auth token. |
| 196 | + |
| 197 | +1. In the MCP Inspector, select `Streamable HTTP` as the Transport Type and enter `http://127.0.0.1:5000/mcp` as the URL. |
| 198 | +1. Click **Connect**. This triggers the OAuth flow, and you are redirected to the Auth0 login page. |
| 199 | +1. Log in with the credentials you set up in the Auth0 connection and allow MCP Inspector access. |
| 200 | +1. After you connect, the browser redirects back to MCP Inspector. |
| 201 | +1. Click **List Tools** to see the available tools. |
| 202 | +1. Select the `GetAstronautsCurrentlyInSpace` tool listed and click **Run Tool**. |
| 203 | +1. You should see the results of the query, which means the authentication is working correctly. |
| 204 | + |
| 205 | +You can select the **Auth** tab in MCP Inspector to see the details of the authenticated user and the scopes granted. |
| 206 | + |
| 207 | +<ExpansionPanel title="Alternative: Guided OAuth flow in MCP Inspector"> |
| 208 | + |
| 209 | +You can also use the guided OAuth flow in MCP Inspector to test authentication. This gives you a detailed look into each step the client does to connect to the server. |
| 210 | + |
| 211 | +1. Click **Open Auth Settings**. |
| 212 | +1. In the **OAuth Flow Progress** section, click **Continue** to start the **Metadata Discovery** step. |
| 213 | +1. Click **Continue** to start the **Client Registration** step. Expand the **Registered Client Information** step to note the `client_id` value. |
| 214 | +1. Click **Continue** to start the **Preparing Authorization** step. Click the link to open up a new tab to authorize MCP Inspector. |
| 215 | +1. Copy the authorization code and return to MCP Inspector. |
| 216 | +1. Paste the code in the next step **Request Authorization and acquire authorization code** then click **Continue**. |
| 217 | +1. Click **Continue** to start the **Token Request** step. This completes the authentication flow. |
| 218 | + |
| 219 | +Before continuing, you need to set up the Auth0 client to accept an additional callback URL. |
| 220 | + |
| 221 | +1. In your Auth0 dashboard, navigate to **Applications**. |
| 222 | +1. Select the client for **MCP Inspector**. If you have multiple entries, find the `client_id` value from the MCP Inspector. |
| 223 | +1. In the client's **Settings** -> **Application URIs**, copy and paste the existing callback URL. Then, remove the `/debug` suffix. Make sure the URLs are comma-separated. It should look something like this: |
| 224 | + |
| 225 | + ```txt |
| 226 | + http://localhost:6274/oauth/callback/debug, |
| 227 | + http://localhost:6274/oauth/callback |
| 228 | + ``` |
| 229 | + |
| 230 | +1. Back in MCP Inspector, click **Connect**. You are now authenticated and can run tools as usual. |
| 231 | + |
| 232 | +</ExpansionPanel> |
| 233 | + |
| 234 | +## Troubleshooting |
| 235 | + |
| 236 | +### Common Issues |
| 237 | + |
| 238 | +#### MCP Server Won't Start |
| 239 | +- **Error**: "Port 5000 is already in use" |
| 240 | + - 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 |
| 241 | +- **Error**: "Failed to load supergraph configuration" |
| 242 | + - Solution: Verify you're running the command from the repo root directory |
| 243 | + - Solution: Check that the path to `supergraph.yaml` is correct |
| 244 | +- **Error**: "License violation" |
| 245 | + - Solution: Ensure that the `rover dev` command includes valid `APOLLO_KEY` and `APOLLO_GRAPH_REF` values and that your plan supports authentication features. |
| 246 | +- **Error**: "What URL is your subgraph running on?" question in terminal |
| 247 | + - 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. |
| 248 | + |
| 249 | +#### MCP Inspector Connection Issues |
| 250 | +- **Error**: "Failed to connect to server" |
| 251 | + - Solution: Ensure the MCP server is running (check terminal output) |
| 252 | + - Solution: Verify you're using the correct URL (`http://127.0.0.1:5000/mcp`) |
| 253 | + - Solution: Check if your firewall is blocking the connection |
| 254 | + |
| 255 | +### Infinite loop during OAuth flow |
| 256 | +- **Issue**: After logging in to Auth0, MCP Inspector keeps refreshing and doesn't complete the OAuth flow |
| 257 | + - 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. |
| 258 | + - Solution: In MCP Inspector, select **Clear OAuth State** and try connecting again. |
| 259 | + |
| 260 | +### Getting Help |
| 261 | + |
| 262 | +If you're still having issues: |
| 263 | +1. Check the [Apollo MCP Server GitHub issues](https://github.com/apollographql/apollo-mcp-server/issues). |
| 264 | +2. Join the [Apollo Community MCP Server Category](https://community.apollographql.com/c/mcp-server/41). |
| 265 | +3. Contact your Apollo representative for direct support. |
0 commit comments