[Docs] Re-organizing docs pages #308

mabuyo · 2025-08-28T19:35:43Z

Proposal to re-organize docs:

Split up User Guide page into multiple pages, one for each section. This change surfaces the developer workflow higher up to the sidebar navigation.
Replaces Command Reference with YAML Config Reference. This change provides a clearer title to what the page is referring to.
Add new page for Run the MCP Server
Remove Install in favour of co-locating install commands with the Run commands depending on what they're using

With this PR, I aimed to keep the content as-is and focus on re-organizing and placement only. In a follow-up PR I'd like to do a full content review for each page and tighten things up! This is just the bare minimum PR.

Before

After

TODO

Set up redirects to ensure no broken links

apollo-librarian · 2025-08-28T19:35:51Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

9 new, 4 changed, 3 removed

+ (developer-tools)/apollo-mcp-server/(latest)/guides/auth-auth0.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/auth.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/config-file.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/custom-scalars.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/debugging.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/define-tools.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/deploy.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/health-checks.mdx
+ (developer-tools)/apollo-mcp-server/(latest)/run.mdx
* (developer-tools)/apollo-mcp-server/(latest)/best-practices.mdx
* (developer-tools)/apollo-mcp-server/(latest)/index.mdx
* (developer-tools)/apollo-mcp-server/(latest)/quickstart.mdx
* (developer-tools)/apollo-mcp-server/(latest)/_sidebar.yaml
- (developer-tools)/apollo-mcp-server/(latest)/command-reference.mdx
- (developer-tools)/apollo-mcp-server/(latest)/guides/auth.mdx
- (developer-tools)/apollo-mcp-server/(latest)/guides/index.mdx

Build ID: d3472aaba544203ff13a385a
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/d3472aaba544203ff13a385a

DaleSeo

I love the new layout! it’s so much easier to find what I need. 👍

docs/source/run.mdx

jcaudle

This is great stuff. I love how you're making this a lot more approachable.

docs/source/command-reference.mdx

docs/source/guides/auth.mdx

docs/source/_sidebar.yaml

…ing pages)

mabuyo · 2025-09-02T18:19:49Z

cc @DaleSeo (and anyone from @apollographql/graph-tooling team!) -- this PR is ready for official review! I pushed a second iteration based on feedback from y'all and Amanda.

As mentioned in the PR description, I'd like to do a full content review for each page and tighten things up in a separate PR. This just sets the stage for the content organization so that we can focus in on each page for content review afterwards.

DaleSeo

This looks great, thanks for the re-organization! I have just one minor comment.

docs/source/config-file.mdx

esilverm

Structure-wise this is looking a lot better! I think this may need another pass when we add more content but as of right now it looks a lot better and I can find what I need more easily!

docs/source/_sidebar.yaml

mabuyo · 2025-09-02T20:51:09Z

TY for the reviews! 🙌🏽 I'll merge this tomorrow since it's near the end of my day now and I wanna make sure I'm available for a big docs change like this 👀

swcollard · 2025-09-02T21:36:12Z

docs/source/auth.mdx

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


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.

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

jcaudle

This looks like it'll be much easier to navigate. I especially love that you caught the URLs in the README. Nice work!

jcaudle · 2025-09-02T23:15:25Z

README.md

Nice catches on the readme!

Sync main → develop (PR #308)

DaleSeo approved these changes Aug 29, 2025

View reviewed changes

DaleSeo reviewed Aug 29, 2025

View reviewed changes

docs/source/run.mdx Outdated Show resolved Hide resolved

jcaudle reviewed Aug 29, 2025

View reviewed changes

docs/source/command-reference.mdx Outdated Show resolved Hide resolved

docs/source/guides/auth.mdx Outdated Show resolved Hide resolved

docs/source/_sidebar.yaml Outdated Show resolved Hide resolved

docs/source/_sidebar.yaml Outdated Show resolved Hide resolved

mabuyo added 4 commits September 2, 2025 11:30

draft proposal for re-organizing docs

e5b0ec3

simplify pages + sidebar

0729869

remove unused pages

bb5d72a

establish redirects/new links for removed files

d160f3d

mabuyo force-pushed the DXM-203 branch from 576a3a1 to d160f3d Compare September 2, 2025 15:34

mabuyo added 9 commits September 2, 2025 11:49

easy librarian changes (without full content review for already exist…

d6b1005

…ing pages)

fix: missing tool approach in summary

875fb86

style: page titles casing

a205020

fix: librarian failure

819cb82

fix: more broken links

59ea222

fix: table style

1ade199

add back deleted description for config file

bf69c58

trigger librarian

3a856c9

fix: trailing slash in links

802faa7

mabuyo marked this pull request as ready for review September 2, 2025 18:17

mabuyo requested review from a team as code owners September 2, 2025 18:17

mabuyo requested review from DaleSeo and jcaudle September 2, 2025 18:18

mabuyo changed the title ~~[Docs] Draft proposal for re-organizing docs pages~~ [Docs] Re-organizing docs pages Sep 2, 2025

DaleSeo approved these changes Sep 2, 2025

View reviewed changes

docs/source/config-file.mdx Show resolved Hide resolved

esilverm approved these changes Sep 2, 2025

View reviewed changes

docs/source/_sidebar.yaml Show resolved Hide resolved

swcollard reviewed Sep 2, 2025

View reviewed changes

jcaudle approved these changes Sep 2, 2025

View reviewed changes

README.md

Copy link

Contributor

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!

mabuyo merged commit 2de84bf into main Sep 3, 2025
7 checks passed

mabuyo deleted the DXM-203 branch September 3, 2025 14:25

apollo-bot2 mentioned this pull request Sep 3, 2025

Sync main → develop (PR #308) #324

Merged

alocay added a commit that referenced this pull request Sep 3, 2025

Merge pull request #324 from apollographql/sync/main-into-develop-pr-308

c8eb509

Sync main → develop (PR #308)

ronan-apollo mentioned this pull request Sep 9, 2025

[docs] Re-org of pages causing 404s - directs needed #344

Closed


		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.

[Docs] Re-organizing docs pages #308

[Docs] Re-organizing docs pages #308

Uh oh!

Conversation

mabuyo commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposal to re-organize docs:

Before

After

TODO

Uh oh!

apollo-librarian bot commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

DaleSeo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jcaudle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mabuyo commented Sep 2, 2025

Uh oh!

DaleSeo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

esilverm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mabuyo commented Sep 2, 2025

Uh oh!

swcollard Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

mabuyo Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

jcaudle left a comment

Choose a reason for hiding this comment

Uh oh!

jcaudle Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mabuyo commented Aug 28, 2025 •

edited

Loading

apollo-librarian bot commented Aug 28, 2025 •

edited

Loading