Merge pull request #308 from apollographql/DXM-203

[Docs] Re-organizing docs pages

Author: mabuyo

README.md

@@ -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
 

docs/source/_sidebar.yaml

@@ -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"

docs/source/auth.mdx

@@ -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.
+
+## 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).

docs/source/best-practices.mdx

@@ -9,6 +9,14 @@ This feature is in [preview](/graphos/resources/feature-launch-stages#preview).
 
 </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.
+- **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.
+
 ## 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.
@@ -17,8 +25,8 @@ When running Apollo MCP Server with GraphOS, use contract variants whenever poss
 
 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
 
@@ -38,4 +46,4 @@ According to [MCP security best practices](https://modelcontextprotocol.io/speci
 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.