Skip to content

[WIP] (docs) make landing MCP doc root more actionable #414

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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

[WIP] (docs) make landing MCP doc root more actionable #414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
db09f07
make landing doc action-focused, move mcp intro
ronan-apollo Oct 1, 2025
e813e86
fix closing p tag
ronan-apollo Oct 2, 2025
9f877a0
change cards to use embedded JSX instead of HTML
ronan-apollo Oct 2, 2025
0c3b5cd
clean up landing code
ronan-apollo Oct 2, 2025
e312414
style the landing tiles
ronan-apollo Oct 2, 2025
0d4984b
style the landing tiles
ronan-apollo Oct 2, 2025
ace4693
formatting for the mcp landing cards
ronan-apollo Oct 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
25 changes: 25 additions & 0 deletions .netlify/netlify.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
plugins = []
headers = []
redirects = []

[functions]

[functions."*"]

[build]
publish = "/Users/ronanfc/localhost/apollo-mcp-server"
publishOrigin = "default"

[build.environment]

[build.processing]

[build.processing.css]

[build.processing.html]

[build.processing.images]

[build.processing.js]

[build.services]
3 changes: 3 additions & 0 deletions .netlify/state.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"siteId": "42b2ee0e-5fae-4379-983c-fe558b458183"
}
16 changes: 16 additions & 0 deletions agent-config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"mcpServers": {
"<your-mcp-server-name>": {
"command": "<localpath>/apollographql/apollo-mcp-server/target/debug/apollo-mcp-server",
"args": [
"--directory",
"<localpath>/apollographql/apollo-mcp-server/<graphql-directory>",
"--schema",
"myapi.graphql",
"--endpoint",
"https://<mymcpendpoint>.app/",
"--introspection"
]
}
}
}
127 changes: 127 additions & 0 deletions docs/source/how-it-works.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
title: How it Works

Check notice on line 2 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L2 

Titles should be in title case. 'it' and 'is' are generally not capitalized unless they are the first or last word.

```suggestion
title: How it works
```
subtitle: Introduction to MCP and how the Apollo MCP Server works

Check notice on line 3 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L3 

Subtitles for conceptual pages should start with 'Learn' and use sentence case.

```suggestion
subtitle: Learn about MCP and how the Apollo MCP Server works
```
---

Apollo MCP Server provides a standard way for AI models to access and orchestrate your GraphQL APIs.

## What is MCP?

Check notice on line 8 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L8 

For conceptual overviews, headings should use gerunds and sentence case for consistency.

```suggestion
## Defining MCP
```

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open protocol that standardizes how applications provide context to AI models like Large Language Models (LLM). MCP enables LLMs and AI agents to indirectly fetch data from external sources.

MCP follows a client-server architecture. MCP servers expose functions, called _tools_, that MCP clients can invoke.

## What is Apollo MCP Server?

Check notice on line 14 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L14 

For conceptual overviews, headings should use gerunds and sentence case for consistency.

```suggestion
## Defining the Apollo MCP Server
```

Apollo MCP Server is an implementation of an MCP server. It makes GraphQL API operations available to AI clients as MCP tools. You can use Apollo MCP Server with any GraphQL API.

The GraphQL operations can be configured from persisted queries, which are predefined, approved lists of operations that are registered with and maintained by a graph. The operations can also be determined by AI introspecting your graph schema.

Check warning on line 18 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L18 

Use active voice and reader-centric framing ('You can...') instead of passive voice ('can be configured').

```suggestion
You can configure GraphQL operations from persisted queries, which are predefined, approved lists of operations that are registered with and maintained by a graph. An AI can also determine the operations by introspecting your graph schema.
```

Apollo MCP Server is deployable in local environments via Apollo's Rover CLI or in containerized services in your cloud infrastructure. It can expose an MCP endpoint using Streamable HTTP for communication with AI clients.

Check warning on line 20 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L20 

Use active voice and reader-centric framing ('You can deploy...') instead of passive phrasing ('is deployable').

```suggestion
You can deploy Apollo MCP Server in local environments via Apollo's Rover CLI or in containerized services in your cloud infrastructure. It exposes an MCP endpoint using Streamable HTTP for communication with AI clients.
```

## How Apollo MCP Server works

Check notice on line 22 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L22 

For conceptual overviews, headings should use gerunds and sentence case for consistency.

```suggestion
## Understanding the architecture
```

Apollo MCP Server bridges AI applications and your GraphQL APIs, translating GraphQL operations into MCP tools that AI models can discover and use.

```mermaid
graph LR
%% Nodes
AI["AI Application\n(Claude, ChatGPT, etc.)"]
MCPClient["MCP Client\n(Built into AI app)"]
MCPServer["Apollo MCP Server"]
GraphQL["GraphQL API\n(Your Graph)"]
Data["Your Data Sources\n(Databases, APIs, etc.)"]

%% Connections
AI <-->|"Natural Language\nRequests"| MCPClient
MCPClient <-->|"MCP Protocol\n(stdio/Streamable HTTP)"| MCPServer
MCPServer <-->|"GraphQL\nOperations"| GraphQL
GraphQL <-->|"Data\nQueries"| Data

%% Tool Generation
subgraph ToolGeneration[Tool Generation]
direction TB
OpFiles["Operation Files\n(.graphql)"]
PQM["Persisted Query\nManifests"]
Introspection["Schema\nIntrospection"]
Tools["MCP Tools"]

OpFiles --> Tools
PQM --> Tools
Introspection --> Tools
end

MCPServer -.->|"Exposes"| Tools
Tools -.->|"Available to"| MCPClient

%% Styling
classDef default stroke-width:1px
classDef aiClient stroke-width:2px
classDef mcpComponent stroke-width:2px
classDef apolloComponent stroke-width:2px
classDef apiComponent stroke-width:2px
classDef dataComponent stroke-width:2px

class AI aiClient
class MCPClient mcpComponent
class MCPServer apolloComponent
class GraphQL apiComponent
class Data dataComponent
class OpFiles,PQM,Introspection apolloComponent
class Tools mcpComponent
```

The architecture enables intelligent API orchestration through these components:

* AI Applications: Tools like Claude Desktop or ChatGPT connect to Apollo MCP Server through their built-in MCP clients, making requests in natural language.

Check warning on line 76 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L76 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
- AI applications: Tools like Claude Desktop or ChatGPT connect to Apollo MCP Server through their built-in MCP clients, making requests in natural language.
```
* Transport Options: Communication happens over stdio for local development or Streamable HTTP.

Check warning on line 77 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L77 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
- Transport options: Communication happens over stdio for local development or Streamable HTTP.
```
* Tool Generation: Apollo MCP Server creates MCP tools from your GraphQL operations using:

Check warning on line 78 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L78 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
- Tool generation: Apollo MCP Server creates MCP tools from your GraphQL operations using:
```
* Operation Files: Individual `.graphql` files for specific queries or mutations

Check warning on line 79 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L79 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
    - Operation files: Individual <code>.graphql</code> files for specific queries or mutations
```
* Persisted Query Manifests: Pre-approved operation lists from Apollo GraphOS

Check warning on line 80 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L80 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
    - Persisted query manifests: Pre-approved operation lists from Apollo GraphOS
```
* Schema Introspection: Dynamic operation discovery for flexible AI exploration

Check warning on line 81 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L81 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
    - Schema introspection: Dynamic operation discovery for flexible AI exploration
```

* Secure Execution: When invoked, the server executes GraphQL operations against your API endpoint, respecting all existing authentication, headers, and security policies.

Check warning on line 83 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L83 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
- Secure execution: When invoked, the server executes GraphQL operations against your API endpoint, respecting all existing authentication, headers, and security policies.
```
* Existing Infrastructure: Your GraphQL API handles requests normally, with Apollo MCP Server acting as a controlled gateway rather than requiring any changes to your graph.

Check warning on line 84 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L84 

Use hyphens (-) for unordered list items, not asterisks (*). Also, use sentence case for list item titles.

```suggestion
- Existing infrastructure: Your GraphQL API handles requests normally, with Apollo MCP Server acting as a controlled gateway rather than requiring any changes to your graph.
```

This design lets you expose precise GraphQL capabilities to AI while maintaining complete control over data access and security.

### Example usage

Check notice on line 88 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L88 

For conceptual overviews, headings should use gerunds and sentence case for consistency.

```suggestion
### Reviewing an example
```

Once configured, AI applications can use your GraphQL operations naturally:

> User: "Show me the astronauts currently in space"
>
> Claude: *Uses GetAstronautsCurrentlyInSpace tool to query your GraphQL API*
>
> "There are currently 7 astronauts aboard the ISS..."

## Why GraphQL for AI?

Check notice on line 98 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L98 

For conceptual overviews, headings should use gerunds and sentence case for consistency.

```suggestion
## Using GraphQL for AI
```

GraphQL's architecture provides unique advantages for AI-powered API orchestration:

**🎯 Deterministic Execution**: GraphQL's built-in relationship handling and query structure eliminate guesswork for AI models. The graph defines clear paths between data types, ensuring AI agents execute operations in the correct sequence without complex prompt engineering or error-prone orchestration logic.

Check warning on line 102 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L102 

Avoid using emojis that are not on the approved list. Use sentence case for the title part of the list item.

```suggestion
**Deterministic execution**: GraphQL's built-in relationship handling and query structure eliminate guesswork for AI models. The graph defines clear paths between data types, ensuring AI agents execute operations in the correct sequence without complex prompt engineering or error-prone orchestration logic.
```

**🛡️ Policy Enforcement**: Security policies and access controls apply consistently across all services within a single GraphQL query context. This unified enforcement model ensures AI operations respect organizational boundaries, even when spanning multiple underlying APIs or microservices.

Check warning on line 104 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L104 

Avoid using emojis that are not on the approved list. Use sentence case for the title part of the list item.

```suggestion
**Policy enforcement**: Security policies and access controls apply consistently across all services within a single GraphQL query context. This unified enforcement model ensures AI operations respect organizational boundaries, even when spanning multiple underlying APIs or microservices.
```

**⚡ Efficiency**: AI agents can request precisely the data needed in a single GraphQL query, reducing API calls, network overhead, and token usage. This focused approach delivers faster responses and lower operational costs compared to orchestrating multiple REST endpoints.

Check warning on line 106 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L106 

Avoid using emojis that are not on the approved list.

```suggestion
**Efficiency**: AI agents can request precisely the data needed in a single GraphQL query, reducing API calls, network overhead, and token usage. This focused approach delivers faster responses and lower operational costs compared to orchestrating multiple REST endpoints.
```

**🔄 Agility**: The pace of AI development demands infrastructure that can evolve daily. GraphQL's declarative approach lets teams rapidly create, modify, and deploy new AI capabilities through self-service tooling. Product teams can wire up new MCP tools without waiting for custom development, keeping pace with AI's unprecedented velocity.

Check warning on line 108 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L108 

Avoid using emojis that are not on the approved list.

```suggestion
**Agility**: The pace of AI development demands infrastructure that can evolve daily. GraphQL's declarative approach lets teams rapidly create, modify, and deploy new AI capabilities through self-service tooling. Product teams can wire up new MCP tools without waiting for custom development, keeping pace with AI's unprecedented velocity.
```

With Apollo MCP Server, these GraphQL advantages become immediately accessible to AI applications through standardized MCP tools.

## Benefits of Apollo MCP Server

Check notice on line 112 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L112 

For conceptual overviews, headings should use gerunds and sentence case for consistency.

```suggestion
## Reviewing the benefits
```

- **🤖 Enable AI-enabled API orchestration**. With Apollo MCP Server, AI models can act as intelligent orchestrators of their GraphQL API operations. By exposing GraphQL operations as distinct MCP tools, AI clients can dynamically chain these operations together, in combination with other MCP servers and tools to execute complex workflows and automate multi-step processes.

Check warning on line 114 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L114 

Avoid using emojis that are not on the approved list. Use a colon after the list item title instead of a period to connect it to the description.

```suggestion
- **Enable AI-enabled API orchestration**: With Apollo MCP Server, AI models can act as intelligent orchestrators of their GraphQL API operations. By exposing GraphQL operations as distinct MCP tools, AI clients can dynamically chain these operations together, in combination with other MCP servers and tools to execute complex workflows and automate multi-step processes.
```

- **🚀 Connect AI to GraphQL in Minutes**. Developers can expose existing or new GraphQL API operations to AI clients without building complex custom integrations. By translating GraphQL functionalities into standardized MCP tools, Apollo MCP Server can significantly reduce the effort needed to connect AI to diverse data sources.

Check warning on line 116 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L116 

Avoid using emojis that are not on the approved list. Use sentence case for the title. Use the imperative voice ('Expose...') for more direct instructions.

```suggestion
- **Connect AI to GraphQL in minutes**: Expose existing or new GraphQL API operations to AI clients without building complex custom integrations. By translating GraphQL functionalities into standardized MCP tools, Apollo MCP Server can significantly reduce the effort needed to connect AI to diverse data sources.
```

- **🔒 Maintain Full Security Control**. By using pre-defined, pre-approved persisted queries, developers can maintain precise governance over which data and operations AI clients can access. This ensures that AI uses existing security protocols and data access policies.

Check warning on line 118 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L118 

Avoid using emojis that are not on the approved list. Use sentence case for the title. Use the imperative voice ('Use...') for more direct instructions.

```suggestion
- **Maintain full security control**: Use pre-defined, pre-approved persisted queries to maintain precise governance over which data and operations AI clients can access. This ensures that AI uses existing security protocols and data access policies.
```

## Prerequisites

- A GraphQL API
- An MCP Client

## Getting started

Ready to connect AI to your GraphQL API? Follow our [5-minute quickstart](/apollo-mcp-server/quickstart) to see Apollo MCP Server in action, or explore the [config file reference](/apollo-mcp-server/config-file) for detailed configuration options.

Check notice on line 127 in docs/source/how-it-works.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/how-it-works.mdx#L127 

Avoid using 'our' when a more direct phrasing is available. 'Follow the...' is more direct.

```suggestion
Ready to connect AI to your GraphQL API? Follow the [5-minute quickstart](/apollo-mcp-server/quickstart) to see Apollo MCP Server in action, or explore the [config file reference](/apollo-mcp-server/config-file) for detailed configuration options.
```
Loading
Loading