Authorization with Apollo MCP Server

The Apollo MCP Server supports authorizing clients (e.g., LLMs) according to the MCP specification.

The current implementation passes through OAuth tokens from MCP clients directly to upstream GraphQL APIs. You can read more about security considerations when using this feature.

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.

For an example of how to configure Apollo MCP Server with Auth0, see Authorization with Auth0.

Configuring allowed audiences

You can specify which JWT audiences are allowed to access your MCP Server.

Specific audiences

1transport:
2  type: streamable_http
3  auth:
4    servers:
5      - https://auth.example.com
6    audiences:
7      - https://api.example.com
8      - https://mcp.example.com

Set audiences to a list of accepted audience values. The JWT's aud claim must match one of these values for the token to be considered valid.

Allow any audience

1transport:
2  type: streamable_http
3  auth:
4    servers:
5      - https://auth.example.com
6    allow_any_audience: true

If you set allow_any_audience to true (the default is false), Apollo MCP Server will skip audience validation entirely. This means tokens with any audience claim will be accepted.

Configure scope enforcement

Use the scope_mode option to control how the MCP Server validates scopes from OAuth tokens.

Require all scopes (default)

1transport:
2  type: streamable_http
3  auth:
4    servers:
5      - https://auth.example.com
6    scopes:
7      - read
8      - write
9    scope_mode: require_all  # This is the default

The token must have all configured scopes. This is the most restrictive mode.

Require any scope

1transport:
2  type: streamable_http
3  auth:
4    servers:
5      - https://auth.example.com
6    scopes:
7      - read
8      - write
9      - admin
10    scope_mode: require_any

The token must have at least one of the configured scopes. Useful when scopes represent alternative access levels.

Disable scope enforcement

1transport:
2  type: streamable_http
3  auth:
4    servers:
5      - https://auth.example.com
6    scope_mode: disabled

Skip scope enforcement entirely. The server validates token authenticity (signature and audience) but not scopes.

HTTP error responses

Apollo MCP Server returns different HTTP status codes depending on the type of authorization failure, following RFC 6750 and the MCP specification.

WWW-Authenticate header

Every 401 and 403 response includes a WWW-Authenticate header to guide clients through the authorization flow.

401 response — directs the client to the Protected Resource Metadata document and indicates the scopes to request:

1HTTP/1.1 401 Unauthorized
2WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
3                         scope="read write"

403 response — includes error="insufficient_scope" along with the scopes required for the specific operation:

1HTTP/1.1 403 Forbidden
2WWW-Authenticate: Bearer error="insufficient_scope",
3                         scope="user:write admin",
4                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

Clients should use the scope parameter provided by the header as the target scope set when initiating or re-initiating authorization. The scope parameter on a 401 response reflects the globally configured scopes (from auth.scopes). The scope parameter on a 403 response reflects the scopes missing for the specific operation, either from auth.scopes or from overrides.required_scopes.

Performance considerations

Discovery timeout

Authorization server metadata is discovered using OAuth 2.0 Authorization Server Metadata (RFC 8414) and OpenID Connect Discovery. The MCP Server tries multiple discovery URL patterns in sequence until one succeeds.

The discovery_timeout setting controls how long to wait for each discovery URL attempt. The default is 5 seconds per URL.

1transport:
2  type: streamable_http
3  auth:
4    servers:
5      - https://auth.example.com
6    discovery_timeout: 10s  # Increase timeout for slower networks (default: 5s)

Considerations:

• Discovery happens during token validation and can add latency to the first authorized request.

• With multiple fallback URLs (RFC 8414, OIDC Discovery), the cumulative timeout can be 10-15 seconds if all URLs fail.

• Increase the timeout if your OAuth server is on a slow network or responds slowly.

• Decrease the timeout in high-performance environments where fast failure is preferred.

OIDC Discovery compatibility

Per the MCP specification, authorization servers must provide at least one of:

• OAuth 2.0 Authorization Server Metadata (RFC 8414) — served at /.well-known/oauth-authorization-server

• OpenID Connect Discovery 1.0 — served at /.well-known/openid-configuration

Apollo MCP Server supports both and tries them in the following order to maximize compatibility:

The first URL that returns a valid metadata document is used. This means IdPs that only support OIDC Discovery (such as Auth0 and many cloud identity providers) work out of the box without any additional configuration.