Merge pull request #228 from apollographql/docs/mcp-auth

Docs: MCP auth

Author: mabuyo

docs/source/command-reference.mdx

@@ -124,7 +124,7 @@ operations:
     - relative/path/to/your/operations/listing.graphql
 ```
 
-### Config options
+## Configuration options
 
 All fields are optional.
 
@@ -142,7 +142,7 @@ All fields are optional.
 | `schema`         | `SchemaSource`        |                          | Schema configuration                                          |
 | `transport`      | `Transport`           |                          | The type of server transport to use                           |
 
-#### GraphOS configuration
+### GraphOS
 
 These fields are under the top-level `graphos` key and define your GraphOS graph credentials and endpoints.
 
@@ -153,7 +153,7 @@ These fields are under the top-level `graphos` key and define your GraphOS graph
 | `apollo_registry_url`     | `URL`    |         | The URL to use for Apollo's registry                                                                            |
 | `apollo_uplink_endpoints` | `URL`    |         | List of uplink URL overrides. You can also provide this with the `APOLLO_UPLINK_ENDPOINTS` environment variable |
 
-#### Health check configuration
+### Health checks
 
 These fields are under the top-level `health_check` key.
 
@@ -173,7 +173,7 @@ Health checks are only available when using the `streamable_http` transport. The
 
 </Note>
 
-#### Introspection configuration
+### Introspection
 
 These fields are under the top-level `introspection` key. Learn more about the MCP [introspection tools](/apollo-mcp-server/guides#introspection-tools).
 
@@ -188,15 +188,15 @@ These fields are under the top-level `introspection` key. Learn more about the M
 | `validate`           | `object` |         | Validation tool configuration                                         |
 | `validate.enabled`   | `bool`   | `false` | Enable validation tool                                                |
 
-#### Logging configuration
+### Logging
 
 These fields are under the top-level `logging` key.
 
 | Option  | Type                                                | Default  | Description                     |
 | :------ | :-------------------------------------------------- | :------- | :------------------------------ |
 | `level` | `oneOf ["trace", "debug", "info", "warn", "error"]` | `"info"` | The minimum log level to record |
 
-#### Operation source configuration
+### Operation source
 
 These fields are under the top-level `operations` key. The available fields depend on the value of the nested `source` key.
 The default value for `source` is `"infer"`.
@@ -213,7 +213,7 @@ The default value for `source` is `"infer"`.
 | Uplink             | `source` | `"uplink"`       |         | Load operations from an uplink manifest. Note: This source requires an Apollo key and graph reference                                             |
 | Infer              | `source` | `"infer"`        | \*      | Infer where to load operations based on other configuration options.                                                                              |
 
-#### Overrides configuration
+### Overrides
 
 These fields are under the top-level `overrides` key.
 
@@ -224,7 +224,7 @@ These fields are under the top-level `overrides` key.
 | `enable_explorer`            | `bool`                              | `false`  | Expose a tool that returns the URL to open a GraphQL operation in Apollo Explorer. Note: This requires a GraphOS graph reference |
 | `mutation_mode`              | `oneOf ["none", "explicit", "all"]` | `"none"` | Defines the mutation access level for the MCP server                                                                             |
 
-#### Schema source configuration
+### Schema source
 
 These fields are under the top-level `schema` key. The available fields depend on the value of the nested `source` key.
 The default value for `source` is `"uplink"`.
@@ -235,7 +235,7 @@ The default value for `source` is `"uplink"`.
 | Local  | `path`   | `FilePath` |         | Path to the GraphQL schema                                                          |
 | Uplink | `source` | `"uplink"` | \*      | Fetch the schema from uplink. Note: This requires an Apollo key and graph reference |
 
-#### Transport configuration
+### Transport
 
 These fields are under the top-level `transport` key. The available fields depend on the value of the nested `type` key.
 The default value for `type` is `"stdio"`.
@@ -250,8 +250,55 @@ The default value for `type` is `"stdio"`.
 | StreamableHTTP | `address` | `IpAddr`            | `127.0.0.1` | The IP address to bind to                                                                                                     |
 | StreamableHTTP | `port`    | `u16`               | `5000`      | The port to bind to                                                                                                           |
 
-### Mapping rover dev options
 
-You can use the [`rover dev`](/rover/commands/dev) command of Rover CLI v0.32 or later to run an Apollo MCP Server instance for local development.
+### Auth
 
-Running `rover dev --mcp` starts an MCP Server. An optional configuration file path can be provided to configure the MCP server via `rover dev --mcp <PATH/TO/CONFIG>`.
+These fields are under the top-level `transport` key, nested under the `auth` key.
+
+| Option                   | Type           | Default | Description                                                                                        |
+| :----------------------- | :------------- | :------ | :------------------------------------------------------------------------------------------------- |
+| `servers`                | `List<URL>`    |         | List of upstream delegated OAuth servers (must support OIDC metadata discovery endpoint)           |
+| `audiences`              | `List<string>` |         | List of accepted audiences from upstream signed JWTs                                               |
+| `resource`               | `string`       |         | The externally available URL pointing to this MCP server. Can be `localhost` when testing locally. |
+| `resource_documentation` | `string`       |         | Optional link to more documentation relating to this MCP server                                    |
+| `scopes`                 | `List<string>` |         | List of queryable OAuth scopes from the upstream OAuth servers                                     |
+
+Below is an example configuration using `StreamableHTTP` transport with authentication:
+
+```yaml title="mcp.yaml"
+transport:
+  type: streamable_http
+  auth:
+    # List of upstream delegated OAuth servers
+    # Note: These need to support the OIDC metadata discovery endpoint
+    servers:
+    - https://auth.example.com
+
+    # List of accepted audiences from upstream signed JWTs
+    # See: https://www.ory.sh/docs/hydra/guides/audiences
+    audiences:
+    - mcp.example.audience
+
+    # The externally available URL pointing to this MCP server. Can be `localhost`
+    # when testing locally.
+    # Note: Subpaths must be preserved here as well. So append `/mcp` if using
+    # Streamable HTTP or `/sse` is using SSE.
+    resource: https://hosted.mcp.server/mcp
+
+    # Optional link to more documentation relating to this MCP server.
+    resource_documentation: https://info.mcp.server
+
+    # List of queryable OAuth scopes from the upstream OAuth servers
+    scopes:
+    - read
+    - mcp
+    - profile
+```
+
+## Run a local graph with MCP server using `rover dev`
+
+You can use the [`rover dev`](/rover/commands/dev) command of Rover CLI `v0.35` or later to run an Apollo MCP Server instance for local development alongside your local graph. Use the `--mcp` flag to start an MCP server and provide an optional configuration file.
+
+```sh
+rover dev --mcp <PATH/TO/CONFIG>
+```

docs/source/guides/index.mdx

@@ -186,6 +186,62 @@ introspection:
 apollo-mcp-server <path to the preceding config>
 ```
 
+## Set up authorization
+
+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).
+
+Depending on whether you are connecting internal agents (first-party) or external agents (third-party, such as Claude, ChatGPT, or other public AI assistants), the steps to configure authorization will differ.
+
+For internal (first-party) agents, 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, Keycloak, etc)
+- An Apollo Router [configured to use JWT authentication](/graphos/routing/security/jwt)
+
+For external (third-party) agents, in addition to the preceding items, you also need:
+
+- A configuration file for the MCP server that [defines the `auth` settings](/apollo-mcp-server/command-reference#auth)
+
+### Example: Configure authentication with Auth0 and third-party agents
+
+Here is an example of how to set up Apollo MCP Server and Apollo Router, with Auth0 as the Identity Provider for external/third-party access.
+
+1. [Set up an Auth0 API](https://auth0.com/docs/get-started/auth0-overview/set-up-apis). You need your Auth0 domain for the next step.
+2. Configure the Apollo Router to [use JWT authentication](/graphos/routing/security/jwt):
+
+    This example router configuration enforces authentication on all requests and uses the JWKS endpoint provided by Auth0 to validate JWTs:
+
+    ```yaml title="Router configuration for JWT authentication"
+    authorization:
+      require_authentication: true # Enforces authentication on all requests
+    authentication:
+      router:
+        jwt:
+          jwks:
+            - url: https://<AUTH0 DOMAIN>/.well-known/jwks.json
+    ```
+
+3. Configure the MCP server to use the same Auth0 instance for authentication.
+
+    This example MCP server configuration enforces authentication on all requests, delegating the actual login process to your previously-configured Auth0 instance:
+
+    ```yaml title="Example MCP config for authentication"
+    transport:
+      type: streamable_http
+      address: "0.0.0.0"
+
+      auth:
+        servers:
+          - https://<AUTH0 DOMAIN>
+        audiences:
+          - <AUTH0 DEFAULT AUDIENCE>
+        resource: http://localhost:5000
+        scopes:
+          - read:users
+    ```
+
+    Refer to the [Authentication configuration section in the command reference](/apollo-mcp-server/command-reference#auth) for more details on the available `auth` options.
+
+
 ## Deploying the MCP server
 
 There are two ways to deploy and operate the MCP server.