Skip to content

Commit db09f07

Browse files
ronan-apolloronan-apollo
committed
make landing doc action-focused, move mcp intro
* uses card layout to focus MCP docs root on start * moves what is mcp / what is apollo mcp to a new page Signed-off-by: Ronan Flynn-Curran <[email protected]>
1 parent 3b8f7f2 commit db09f07

File tree

2 files changed

+225
-122
lines changed

2 files changed

+225
-122
lines changed

‎docs/source/how-it-works.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: How it Works
3+
subtitle: Introduction to MCP and how the Apollo MCP Server works
4+
---
5+
6+
Apollo MCP Server provides a standard way for AI models to access and orchestrate your GraphQL APIs.
7+
8+
## What is MCP?
9+
10+
[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.
11+
12+
MCP follows a client-server architecture. MCP servers expose functions, called _tools_, that MCP clients can invoke.
13+
14+
## What is Apollo MCP Server?
15+
16+
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.
17+
18+
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.
19+
20+
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.
21+
22+
## How Apollo MCP Server works
23+
24+
Apollo MCP Server bridges AI applications and your GraphQL APIs, translating GraphQL operations into MCP tools that AI models can discover and use.
25+
26+
```mermaid
27+
graph LR
28+
%% Nodes
29+
AI["AI Application\n(Claude, ChatGPT, etc.)"]
30+
MCPClient["MCP Client\n(Built into AI app)"]
31+
MCPServer["Apollo MCP Server"]
32+
GraphQL["GraphQL API\n(Your Graph)"]
33+
Data["Your Data Sources\n(Databases, APIs, etc.)"]
34+
35+
%% Connections
36+
AI <-->|"Natural Language\nRequests"| MCPClient
37+
MCPClient <-->|"MCP Protocol\n(stdio/Streamable HTTP)"| MCPServer
38+
MCPServer <-->|"GraphQL\nOperations"| GraphQL
39+
GraphQL <-->|"Data\nQueries"| Data
40+
41+
%% Tool Generation
42+
subgraph ToolGeneration[Tool Generation]
43+
direction TB
44+
OpFiles["Operation Files\n(.graphql)"]
45+
PQM["Persisted Query\nManifests"]
46+
Introspection["Schema\nIntrospection"]
47+
Tools["MCP Tools"]
48+
49+
OpFiles --> Tools
50+
PQM --> Tools
51+
Introspection --> Tools
52+
end
53+
54+
MCPServer -.->|"Exposes"| Tools
55+
Tools -.->|"Available to"| MCPClient
56+
57+
%% Styling
58+
classDef default stroke-width:1px
59+
classDef aiClient stroke-width:2px
60+
classDef mcpComponent stroke-width:2px
61+
classDef apolloComponent stroke-width:2px
62+
classDef apiComponent stroke-width:2px
63+
classDef dataComponent stroke-width:2px
64+
65+
class AI aiClient
66+
class MCPClient mcpComponent
67+
class MCPServer apolloComponent
68+
class GraphQL apiComponent
69+
class Data dataComponent
70+
class OpFiles,PQM,Introspection apolloComponent
71+
class Tools mcpComponent
72+
```
73+
74+
The architecture enables intelligent API orchestration through these components:
75+
76+
* AI Applications: Tools like Claude Desktop or ChatGPT connect to Apollo MCP Server through their built-in MCP clients, making requests in natural language.
77+
* Transport Options: Communication happens over stdio for local development or Streamable HTTP.
78+
* Tool Generation: Apollo MCP Server creates MCP tools from your GraphQL operations using:
79+
* Operation Files: Individual `.graphql` files for specific queries or mutations
80+
* Persisted Query Manifests: Pre-approved operation lists from Apollo GraphOS
81+
* Schema Introspection: Dynamic operation discovery for flexible AI exploration
82+
83+
* Secure Execution: When invoked, the server executes GraphQL operations against your API endpoint, respecting all existing authentication, headers, and security policies.
84+
* 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.
85+
86+
This design lets you expose precise GraphQL capabilities to AI while maintaining complete control over data access and security.
87+
88+
### Example usage
89+
90+
Once configured, AI applications can use your GraphQL operations naturally:
91+
92+
> User: "Show me the astronauts currently in space"
93+
>
94+
> Claude: *Uses GetAstronautsCurrentlyInSpace tool to query your GraphQL API*
95+
>
96+
> "There are currently 7 astronauts aboard the ISS..."
97+
98+
## Why GraphQL for AI?
99+
100+
GraphQL's architecture provides unique advantages for AI-powered API orchestration:
101+
102+
**🎯 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.
103+
104+
**🛡️ 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.
105+
106+
**⚡ 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.
107+
108+
**🔄 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.
109+
110+
With Apollo MCP Server, these GraphQL advantages become immediately accessible to AI applications through standardized MCP tools.
111+
112+
## Benefits of Apollo MCP Server
113+
114+
- **🤖 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.
115+
116+
- **🚀 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.
117+
118+
- **🔒 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.
119+
120+
## Prerequisites
121+
122+
- A GraphQL API
123+
- An MCP Client
124+
125+
## Getting started
126+
127+
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.

‎docs/source/index.mdx‎

Lines changed: 98 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -12,125 +12,101 @@ This feature is in [preview](/graphos/resources/feature-launch-stages#preview).
1212

1313
</PreviewFeature>
1414

15-
Apollo MCP Server provides a standard way for AI models to access and orchestrate your APIs running with Apollo.
16-
17-
## What is MCP?
18-
19-
[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.
20-
21-
MCP follows a client-server architecture. MCP servers expose functions, called _tools_, that MCP clients can invoke.
22-
23-
## What is Apollo MCP Server?
24-
25-
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.
26-
27-
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.
28-
29-
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.
30-
31-
## How Apollo MCP Server works
32-
33-
Apollo MCP Server bridges AI applications and your GraphQL APIs, translating GraphQL operations into MCP tools that AI models can discover and use.
34-
35-
```mermaid
36-
graph LR
37-
%% Nodes
38-
AI["AI Application\n(Claude, ChatGPT, etc.)"]
39-
MCPClient["MCP Client\n(Built into AI app)"]
40-
MCPServer["Apollo MCP Server"]
41-
GraphQL["GraphQL API\n(Your Graph)"]
42-
Data["Your Data Sources\n(Databases, APIs, etc.)"]
43-
44-
%% Connections
45-
AI <-->|"Natural Language\nRequests"| MCPClient
46-
MCPClient <-->|"MCP Protocol\n(stdio/Streamable HTTP)"| MCPServer
47-
MCPServer <-->|"GraphQL\nOperations"| GraphQL
48-
GraphQL <-->|"Data\nQueries"| Data
49-
50-
%% Tool Generation
51-
subgraph ToolGeneration[Tool Generation]
52-
direction TB
53-
OpFiles["Operation Files\n(.graphql)"]
54-
PQM["Persisted Query\nManifests"]
55-
Introspection["Schema\nIntrospection"]
56-
Tools["MCP Tools"]
57-
58-
OpFiles --> Tools
59-
PQM --> Tools
60-
Introspection --> Tools
61-
end
62-
63-
MCPServer -.->|"Exposes"| Tools
64-
Tools -.->|"Available to"| MCPClient
65-
66-
%% Styling
67-
classDef default stroke-width:1px
68-
classDef aiClient stroke-width:2px
69-
classDef mcpComponent stroke-width:2px
70-
classDef apolloComponent stroke-width:2px
71-
classDef apiComponent stroke-width:2px
72-
classDef dataComponent stroke-width:2px
73-
74-
class AI aiClient
75-
class MCPClient mcpComponent
76-
class MCPServer apolloComponent
77-
class GraphQL apiComponent
78-
class Data dataComponent
79-
class OpFiles,PQM,Introspection apolloComponent
80-
class Tools mcpComponent
81-
```
82-
83-
The architecture enables intelligent API orchestration through these components:
84-
85-
* AI Applications: Tools like Claude Desktop or ChatGPT connect to Apollo MCP Server through their built-in MCP clients, making requests in natural language.
86-
* Transport Options: Communication happens over stdio for local development or Streamable HTTP.
87-
* Tool Generation: Apollo MCP Server creates MCP tools from your GraphQL operations using:
88-
* Operation Files: Individual `.graphql` files for specific queries or mutations
89-
* Persisted Query Manifests: Pre-approved operation lists from Apollo GraphOS
90-
* Schema Introspection: Dynamic operation discovery for flexible AI exploration
91-
92-
* Secure Execution: When invoked, the server executes GraphQL operations against your API endpoint, respecting all existing authentication, headers, and security policies.
93-
* 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.
94-
95-
This design lets you expose precise GraphQL capabilities to AI while maintaining complete control over data access and security.
96-
97-
### Example usage
98-
99-
Once configured, AI applications can use your GraphQL operations naturally:
100-
101-
> User: "Show me the astronauts currently in space"
102-
>
103-
> Claude: *Uses GetAstronautsCurrentlyInSpace tool to query your GraphQL API*
104-
>
105-
> "There are currently 7 astronauts aboard the ISS..."
106-
107-
## Why GraphQL for AI?
108-
109-
GraphQL's architecture provides unique advantages for AI-powered API orchestration:
110-
111-
**🎯 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.
112-
113-
**🛡️ 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.
114-
115-
**⚡ 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.
116-
117-
**🔄 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.
118-
119-
With Apollo MCP Server, these GraphQL advantages become immediately accessible to AI applications through standardized MCP tools.
120-
121-
## Benefits of Apollo MCP Server
122-
123-
- **🤖 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.
124-
125-
- **🚀 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.
126-
127-
- **🔒 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.
128-
129-
## Prerequisites
130-
131-
- A GraphQL API
132-
- An MCP Client
133-
134-
## Getting started
135-
136-
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.
15+
Apollo MCP Server provides a standard way for AI models to access and orchestrate your Graph APIs - by making GraphQL API operations available to AI clients as MCP tools. You can use Apollo MCP Server with any GraphQL API.
16+
17+
<!-- Benefits -->
18+
- **AI-enabled API orchestration**: AI models can act as intelligent orchestrators of GraphQL API operations, dynamically chaining operations to execute complex workflows and automate multi-step processes.
19+
- **More Efficient Tools for Agents**:Combining MCP tools and GraphQL operations means smarter schema search and discovery - reducing context usage and improving agent efficiency. [Learn more](https://www.apollographql.com/blog/smart-schema-discovery-how-apollo-mcp-server-maximizes-ai-context-efficiency)
20+
21+
- **Maintain Full Security Control**: Use pre-defined, pre-approved persisted queries to maintain precise governance over which data and operations AI clients can access.
22+
23+
24+
<!-- Getting Started CTA -->
25+
<div class="mb-16 rounded-lg border border-blue-200 bg-gradient-to-r from-blue-50 to-indigo-50 p-8">
26+
<h2 class="mb-4 text-2xl font-bold">Getting Started</h2>
27+
<p class="mb-6 text-gray-700">Get up and running in a couple of minutes with the Quickstart. Topics include how to:
28+
29+
<ul class="list-inside list-disc space-y-2 text-gray-700 mb-6">
30+
<li>creating your own MCP server (starting from scratch or using an existing Graph)</li>
31+
<li>connect and test your MCP server in an AI client application (like Claude or Cursor)</li>
32+
<li>exposing your GraphQL API operations as MCP tools </li>
33+
</ul>
34+
35+
</p>
36+
<div class="flex gap-4">
37+
<a href="/docs/apollo-mcp-server/quickstart" class="inline-block rounded-lg bg-blue-600 px-6 py-3 font-semibold text-white transition hover:bg-blue-700">Quickstart → </a>
38+
</div>
39+
</div>
40+
41+
<!-- Feature Cards -->
42+
<div class="mb-12">
43+
<h2 class="mb-6 text-2xl font-bold">Key Features & Guides</h2>
44+
45+
<div class="grid w-full grid-cols-2 gap-4">
46+
47+
<div class="rounded-lg border border-gray-200 p-5 transition hover:shadow-md">
48+
<div class="text-3xl">📘</div>
49+
<div>
50+
<h3 class="mb-2 font-semibold">
51+
<a href="/docs/apollo-mcp-server/how-it-works" class="text-blue-600 hover:underline">How It Works</a>
52+
</h3>
53+
<p class="text-sm text-gray-600">Understand the MCP architecture and how Apollo MCP Server works.</p>
54+
</div>
55+
</div>
56+
57+
<!-- Running MCP Server -->
58+
<div class="rounded-lg border border-gray-200 p-5 transition hover:shadow-md">
59+
<div class="mb-3 text-2xl">🚀</div>
60+
<h3 class="mb-2 font-semibold">
61+
<a href="/docs/apollo-mcp-server/running" class="text-blue-600 hover:underline">Running the MCP Server</a>
62+
</h3>
63+
<p class="text-sm text-gray-600">Run the server locally with <code>rover dev</code> or in containerized services.</p>
64+
</div>
65+
66+
<!-- Tool Definition -->
67+
<div class="rounded-lg border border-gray-200 p-5 transition hover:shadow-md">
68+
<div class="mb-3 text-2xl">🔧</div>
69+
<h3 class="mb-2 font-semibold">
70+
<a href="/docs/apollo-mcp-server/tool-definition" class="text-blue-600 hover:underline">Tool Definition</a>
71+
</h3>
72+
<p class="text-sm text-gray-600">Create MCP tools from operation files, persisted queries, or schema introspection.</p>
73+
</div>
74+
75+
<!-- Configuration -->
76+
<div class="rounded-lg border border-gray-200 p-5 transition hover:shadow-md">
77+
<div class="mb-3 text-2xl">⚙️</div>
78+
<h3 class="mb-2 font-semibold">
79+
<a href="/docs/apollo-mcp-server/configuration" class="text-blue-600 hover:underline">Configuration</a>
80+
</h3>
81+
<p class="text-sm text-gray-600">Configure transport options, endpoints, and GraphQL operations.</p>
82+
</div>
83+
84+
<!-- Deploying -->
85+
<div class="rounded-lg border border-gray-200 p-5 transition hover:shadow-md">
86+
<div class="mb-3 text-2xl">☁️</div>
87+
<h3 class="mb-2 font-semibold">
88+
<a href="/docs/apollo-mcp-server/deploying" class="text-blue-600 hover:underline">Deployment</a>
89+
</h3>
90+
<p class="text-sm text-gray-600">Deploy to cloud infrastructure with containerization guides.</p>
91+
</div>
92+
93+
<!-- Telemetry -->
94+
<div class="rounded-lg border border-gray-200 p-5 transition hover:shadow-md">
95+
<div class="mb-3 text-2xl">📊</div>
96+
<h3 class="mb-2 font-semibold">
97+
<a href="/docs/apollo-mcp-server/telemetry" class="text-blue-600 hover:underline">Telemetry</a>
98+
</h3>
99+
<p class="text-sm text-gray-600">Observe your MCP server requests and performance.</p>
100+
</div>
101+
102+
<!-- Authentication -->
103+
<div class="rounded-lg border border-gray-200 p-5 transition hover:shadow-md">
104+
<div class="mb-3 text-2xl">🔐</div>
105+
<h3 class="mb-2 font-semibold">
106+
<a href="/docs/apollo-mcp-server/authentication" class="text-blue-600 hover:underline">Auth</a>
107+
</h3>
108+
<p class="text-sm text-gray-600">Secure your MCP server with headers and authorization.</p>
109+
</div>
110+
</div>
111+
</div>
112+
</div>

0 commit comments

Comments
 (0)