Skip to content

[Docs] Re-organizing docs pages #308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Sep 3, 2025
Merged

[Docs] Re-organizing docs pages #308

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
e5b0ec3
draft proposal for re-organizing docs
mabuyo Aug 28, 2025
0729869
simplify pages + sidebar
mabuyo Sep 2, 2025
bb5d72a
remove unused pages
mabuyo Sep 2, 2025
d160f3d
establish redirects/new links for removed files
mabuyo Sep 2, 2025
d6b1005
easy librarian changes (without full content review for already exist…
mabuyo Sep 2, 2025
875fb86
fix: missing tool approach in summary
mabuyo Sep 2, 2025
a205020
style: page titles casing
mabuyo Sep 2, 2025
819cb82
fix: librarian failure
mabuyo Sep 2, 2025
59ea222
fix: more broken links
mabuyo Sep 2, 2025
1ade199
fix: table style
mabuyo Sep 2, 2025
bf69c58
add back deleted description for config file
mabuyo Sep 2, 2025
3a856c9
trigger librarian
mabuyo Sep 2, 2025
802faa7
fix: trailing slash in links
mabuyo Sep 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Copy link
Contributor

@jcaudle jcaudle Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catches on the readme!

Original file line number Diff line number Diff line change
Expand Up @@ -18,22 +18,22 @@ See [the documentation](https://www.apollographql.com/docs/apollo-mcp-server/) f

## Installation

You can either build this server from source, if you have Rust installed on your workstation, or you can follow the [installation guide](https://www.apollographql.com/docs/apollo-mcp-server/install). To build from source, run `cargo build` from the root of this repository and the server will be built in the `target/debug` directory.
You can either build this server from source, if you have Rust installed on your workstation, or you can follow the [installation guide](https://www.apollographql.com/docs/apollo-mcp-server/run). To build from source, run `cargo build` from the root of this repository and the server will be built in the `target/debug` directory.

## Getting started

Follow the [quickstart tutorial](https://www.apollographql.com/docs/apollo-mcp-server/quickstart) to get started with this server.

## Usage

Full usage of Apollo MCP Server is documented on the [user guide](https://www.apollographql.com/docs/apollo-mcp-server/guides). There are a few items that are necessary for this server to function. Specifically, the following things must be configured:
Full usage of Apollo MCP Server is documented on the [user guide](https://www.apollographql.com/docs/apollo-mcp-server/run). There are a few items that are necessary for this server to function. Specifically, the following things must be configured:

1. A graph for the MCP server to sit in front of.
2. Definitions for the GraphQL operations that should be exposed as MCP tools.
3. A configuration file describing how the MCP server should run.
4. A connection to an MCP client, such as an LLM or [MCP inspector](https://modelcontextprotocol.io/legacy/tools/inspector).

These are all described on the user guide. Specific configuration options for the configuration file are documented in the [command reference](https://www.apollographql.com/docs/apollo-mcp-server/command-reference).
These are all described on the user guide. Specific configuration options for the configuration file are documented in the [config file reference](https://www.apollographql.com/docs/apollo-mcp-server/config-file).

## Contributions

Expand Down
33 changes: 25 additions & 8 deletions docs/source/_sidebar.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,39 @@ switcher:
- label: v0
latest: true
href: ./
defaultOpenDepth: 2
items:
- label: "Welcome"
- label: "Overview"
href: "."
- label: "Quickstart"
href: "./quickstart"
- label: "Install"
href: "./install"
- label: "User Guide"
href: "./guides"
- label: "Define tools"
href: "./define-tools"
- label: "Configuration"
children:
- label: "YAML Config Reference"
href: "./config-file"
- label: "Custom Scalars"
href: "./custom-scalars"
- label: "Run the MCP Server"
href: "./run"
- label: "Debugging"
href: "./debugging"
- label: "Deployment"
children:
- label: "Overview"
href: "./deploy"
- label: "Health Checks"
href: "./health-checks"
- label: "Authorization"
href: "./guides/auth"
- label: "Command Reference"
href: "./command-reference"
href: "./auth"
- label: "Best Practices"
href: "./best-practices"
- label: "Licensing"
href: "./licensing"
- label: "Limitations"
href: "./limitations"
- label: "Guides"
children:
- label: "Authorization with Auth0"
href: "./guides/auth-auth0"
21 changes: 21 additions & 0 deletions docs/source/auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
title: Authorization with Apollo MCP Server
redirectFrom:
- /apollo-mcp-server/guides/auth
---

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).

The current implementation passes through OAuth tokens from MCP clients directly to upstream GraphQL APIs. You can read more about [security considerations](/apollo-mcp-server/limitations#oauth-token-passthrough) when using this feature.
Copy link
Contributor

@swcollard swcollard Sep 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The current implementation passes through OAuth tokens from MCP clients directly to upstream GraphQL APIs. You can read more about [security considerations](/apollo-mcp-server/limitations#oauth-token-passthrough) when using this feature.
The current implementation passes through validated OAuth tokens from MCP clients directly to upstream GraphQL APIs. You can read more about [security considerations](/apollo-mcp-server/limitations#oauth-token-passthrough) when using this feature.

We've had some confusion around the token passthrough, so I think it would be good to call out that the tokens we do pass to the graphql API have been validated by the MCP server using their configured oauth provider.

Copy link
Contributor Author

@mabuyo mabuyo Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! I've added this note to a separate ticket where we tackle updating the Auth pages


## Implement authorization with Apollo MCP Server

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:

- **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](/apollo-mcp-server/config-file#auth) and the [GraphOS Router for JWT authentication](/graphos/routing/security/jwt) using those IdP values.

For an example of how to configure Apollo MCP Server with Auth0, see [Authorization with Auth0](/apollo-mcp-server/guides/auth-auth0).
14 changes: 11 additions & 3 deletions docs/source/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@

</PreviewFeature>

## Writing your schema for efficient MCP tools

The schema is required for:

- **Tool Descriptions**: The schema provides type information used to generate tool descriptions. You can override these descriptions by adding comments to your operation files.

Check warning on line 16 in docs/source/best-practices.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/best-practices.mdx#L16 

List items that are complete sentences must end with a period.

```suggestion
- **Tool Descriptions**: The schema provides type information used to generate tool descriptions. You can override these descriptions by adding comments to your operation files..
```
- **Input Validation**: The schema is used to translate GraphQL input types into JSON Schema, ensuring that AI models provide correctly formatted inputs.

Check warning on line 17 in docs/source/best-practices.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/best-practices.mdx#L17 

List items that are complete sentences must end with a period.

```suggestion
- **Input Validation**: The schema is used to translate GraphQL input types into JSON Schema, ensuring that AI models provide correctly formatted inputs..
```
- **Introspection Support**: If you enable the `introspection` option, the schema is used to provide information about available types and operations to AI models.

Check warning on line 18 in docs/source/best-practices.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/best-practices.mdx#L18 

List items that are complete sentences must end with a period.

```suggestion
- **Introspection Support**: If you enable the <code>introspection</code> option, the schema is used to provide information about available types and operations to AI models..
```

## Use contract variants to control AI access to graphs

GraphOS [contract variants](/graphos/platform/schema-management/delivery/contracts/overview) let you deliver different subsets of your graph to different consumers.
Expand All @@ -17,8 +25,8 @@

In particular, we strongly recommend contract variants when using:

- [GraphOS-managed persisted queries](/apollo-mcp-server/guides#from-graphos-managed-persisted-queries)
- [Introspection](/apollo-mcp-server/guides#introspection-tools)
- [GraphOS-managed persisted queries](/apollo-mcp-server/define-tools#from-graphos-managed-persisted-queries)
- [Introspection](/apollo-mcp-server/define-tools#introspection-tools)

## Send client name header when using persisted queries

Expand All @@ -38,4 +46,4 @@
To maintain clear trust boundaries, MCP servers must only accept tokens explicitly issued for themselves and must act as independent OAuth clients when calling upstream services.
Forwarding client tokens downstream is not allowed.

Apollo MCP Server supports OAuth 2.1 authentication that follows best practices and aligns with the MCP authorization model. See our [authorization guide](/apollo-mcp-server/guides/auth) for implementation details.
Apollo MCP Server supports OAuth 2.1 authentication that follows best practices and aligns with the MCP authorization model. See our [authorization guide](/apollo-mcp-server/auth) for implementation details.
Loading