Skip to content

Commit b335da6

Browse files
pragljerelmiller
pragl
and
jerelmiller
authored
Adding docs for MCP Apps (#636)
* Adding docs for MCP Apps * Removing mention of flag from troubleshooting page * Addressing technical-review comments * Converting reference to table-driven * Fixing some errors. * Fixing formatting * Applying improvements to reference doc. * Correcting diagrams. * Updating with latest edits * Fixing typo. * Applying Jerel's feedback * Fixing table error * Including Jerel's updates to reference doc * Additional docs on developing the application (#659) Co-authored-by: Parker <parker.ragland@apollographql.com> --------- Co-authored-by: Jerel Miller <jerelmiller@gmail.com>
1 parent 103678c commit b335da6

File tree

8 files changed

+1077
-0
lines changed

8 files changed

+1077
-0
lines changed

‎docs/source/_sidebar.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,20 @@ items:
4040
href: "./licensing"
4141
- label: "Limitations"
4242
href: "./limitations"
43+
- label: "MCP Apps"
44+
children:
45+
- label: "Overview"
46+
href: "./mcp-apps"
47+
- label: "Prerequisites"
48+
href: "./mcp-apps-prerequisites"
49+
- label: "Quickstart"
50+
href: "./mcp-apps-quickstart"
51+
- label: "MCP App Development"
52+
href: "./mcp-apps-development"
53+
- label: "Architecture"
54+
href: "./mcp-apps-architecture"
55+
- label: "Reference"
56+
href: "./mcp-apps-reference"
4357
- label: "Guides"
4458
children:
4559
- label: "Development to Production Workflows"

‎docs/source/index.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,8 @@ With Apollo MCP Server, these GraphQL advantages become immediately accessible t
118118

119119
- **🚀 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.
120120

121+
- **🎨 Build Custom Interactive Experiences**. With MCP Apps support, you can create custom, interactive experiences in any host that supports the MCP Apps specification (such as ChatGPT). Control how your data appears with custom HTML/UI resources, enabling rich visualizations, interactive forms, and branded experiences powered by your GraphQL APIs.
122+
121123
- **🔒 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.
122124

123125
## Prerequisites
@@ -128,3 +130,5 @@ With Apollo MCP Server, these GraphQL advantages become immediately accessible t
128130
## Getting started
129131

130132
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.
133+
134+
Want to build custom interactive experiences? Check out the [MCP Apps quickstart](/apollo-mcp-server/mcp-apps-quickstart) to create your first MCP App.

‎docs/source/mcp-apps-architecture.mdx‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: MCP Apps Architecture
3+
subtitle: How MCP Apps work with Apollo MCP Server
4+
---
5+
6+
MCP Apps combine GraphQL operations with custom UI resources to create interactive experiences in MCP Apps-compatible hosts. Apollo MCP Server bridges your GraphQL APIs to the MCP Apps specification.
7+
8+
## High-level flow
9+
10+
MCP Apps work in two phases:
11+
12+
**Discovery phase**: The host discovers your app and pre-fetches the built resource.
13+
14+
**Tool execution phase**: When a tool is invoked, the host receives data from the MCP server and injects it into a pre-loaded iframe.
15+
16+
```mermaid
17+
graph TB
18+
subgraph Discovery["Discovery Phase"]
19+
Host1["MCP Apps Host"]
20+
MCPServer1["Apollo MCP Server"]
21+
22+
Host1 -->|"1. List Resources"| MCPServer1
23+
MCPServer1 -->|"2. Return Resource URI"| Host1
24+
Host1 -->|"3. Read Resource"| MCPServer1
25+
MCPServer1 -->|"4. Return UI Content"| Host1
26+
end
27+
28+
subgraph Execution["Tool Execution Phase"]
29+
Host2["MCP Apps Host"]
30+
MCPServer2["Apollo MCP Server"]
31+
GraphQL["GraphQL API"]
32+
Iframe["Iframe with UI"]
33+
34+
Host2 -->|"5. Invoke Tool"| MCPServer2
35+
MCPServer2 -->|"6. Execute GraphQL"| GraphQL
36+
GraphQL -->|"7. Return Data"| MCPServer2
37+
MCPServer2 -->|"8. Return Data"| Host2
38+
Host2 -->|"9. Create Iframe"| Iframe
39+
Host2 -->|"10. Inject Data"| Iframe
40+
end
41+
42+
style Host1 fill:#E3F2FD
43+
style Host2 fill:#E3F2FD
44+
style MCPServer1 fill:#1976D2,color:#fff
45+
style MCPServer2 fill:#1976D2,color:#fff
46+
style GraphQL fill:#00ACC1,color:#fff
47+
style Iframe fill:#4CAF50,color:#fff
48+
```
49+
50+
When an MCP Apps-compatible host invokes a tool, Apollo MCP Server executes the GraphQL operation and returns only the data. The host then creates an iframe with the pre-fetched HTML resource and injects the tool result data into it.
51+
52+
## App components
53+
54+
An MCP App consists of:
55+
56+
- **Tools**: GraphQL operations exposed as MCP tools that MCP Apps-compatible hosts can invoke
57+
- **Resource**: The built `.html` file that contains your application code.
58+
59+
The app manifest (`.application-manifest.json`) is automatically generated from your app code and your configuration file (or `package.json`). GraphQL operations come from your app code, while app-level configuration comes from your configuration files. The manifest defines the mapping between tools, operations, and the resource.
60+
61+
## App structure
62+
63+
Apps are organized in directories under `apps/`, each containing build artifacts (the manifest file and built resources). The MCP Server reads from the `apps/` directory.
64+
65+
**Important**: The `apps/` directory contains build artifacts, not your development code. Development happens in a separate directory (we recommend using `dev/<app-name>`, like the [Apollo AI Apps Template](https://github.com/apollographql/ai-apps-template) does).
66+
67+
68+
## Resources
69+
70+
The resource is the built `.html` file that contains your application code. This file is loaded by the host and contains everything needed to render your app's UI. We recommend using the [Apollo AI Apps Template](https://github.com/apollographql/ai-apps-template) for a complete setup.
71+
72+
## App target selection
73+
74+
Apollo MCP Server supports two app targets:
75+
- ChatGPT Apps: For hosts that support OpenAI's Apps SDK specification (for example, ChatGPT)
76+
- MCP Apps: MCP Apps-compatible clients
77+
78+
The target determines MIME type, metadata format, and CSP format.

0 commit comments

Comments
 (0)