OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add apollographql/skills --skill apollo-mcp-server
Guide for using Apollo MCP Server to connect AI agents with GraphQL APIs. Use this skill when: (1) setting up or configuring Apollo MCP Server, (2) defining MCP tools from GraphQL operations, (3) using introspection tools (introspect, search, validate, execute), (4) troubleshooting MCP server connectivity or tool execution issues.
npx skills add apollographql/skills --skill apollo-mcp-server
Apollo MCP Server exposes GraphQL operations as MCP tools, enabling AI agents to interact with GraphQL APIs through the Model Context Protocol.
Create config.yaml in your project root:
Start the server:
The MCP endpoint is available at http://127.0.0.1:8000/mcp (streamable_http defaults: address 127.0.0.1, port 8000). The GraphQL endpoint defaults to http://localhost:4000/ — override with the endpoint key if your API runs elsewhere.
Add to your MCP client configuration:
Streamable HTTP (recommended):
Claude Desktop (claude_desktop_config.json):
Claude Code:
Stdio (client launches the server directly):
Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):
Apollo MCP Server provides four introspection tools:
| Tool | Purpose | When to Use |
|---|---|---|
introspect | Explore schema types in detail | Need type definitions, fields, relationships |
search | Find types in schema | Looking for specific types or fields |
validate | Check operation validity | Before executing operations |
execute | Run ad-hoc GraphQL operations | Testing or one-off queries |
MCP tools are created from GraphQL operations. Three methods:
Each file must contain exactly one operation. Each named operation becomes an MCP tool.
Use GraphOS Studio to manage operations collaboratively.
For production environments with pre-approved operations.
Detailed documentation for specific topics:
headers configuration for API keys and tokensoverrides.mutation_mode: explicit to require confirmation for mutationsEnable minification to reduce token usage:
Minified output uses compact notation:
Control mutation behavior via the overrides section:
mutation_mode: explicit or mutation_mode: none in shared environments# config.yaml
transport:
type: streamable_http
schema:
source: local
path: ./schema.graphql
operations:
source: local
paths:
- ./operations/
introspection:
introspect:
enabled: true
search:
enabled: true
validate:
enabled: true
execute:
enabled: trueapollo-mcp-server ./config.yaml{
"mcpServers": {
"graphql-api": {
"command": "npx",
"args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
}
}
}claude mcp add graphql-api -- npx mcp-remote http://127.0.0.1:8000/mcp{
"mcpServers": {
"graphql-api": {
"command": "./apollo-mcp-server",
"args": ["./config.yaml"]
}
}
}operations:
source: local
paths:
- ./operations/# operations/GetUser.graphql
query GetUser($id: ID!) {
user(id: $id) {
id
name
email
}
}# operations/CreateUser.graphql
mutation CreateUser($input: CreateUserInput!) {
createUser(input: $input) {
id
name
}
}operations:
source: collection
id: your-collection-idoperations:
source: manifest
path: ./persisted-query-manifest.json# Static header
headers:
Authorization: "Bearer ${env.API_TOKEN}"
# Dynamic header forwarding
forward_headers:
- x-forwarded-token
# OAuth (streamable_http transport)
transport:
type: streamable_http
auth:
servers:
- https://auth.example.com/.well-known/openid-configuration
audiences:
- https://api.example.comintrospection:
introspect:
minify: true
search:
minify: trueoverrides:
mutation_mode: all # Execute mutations directly
# mutation_mode: explicit # Require explicit confirmation
# mutation_mode: none # Block all mutations (default)# schema.source defaults to uplink — can be omitted when graphos is configured
graphos:
apollo_key: ${env.APOLLO_KEY}
apollo_graph_ref: my-graph@productiontransport:
type: streamable_http
schema:
source: local
path: ./schema.graphql
introspection:
introspect:
enabled: true
search:
enabled: true
validate:
enabled: true
execute:
enabled: true
overrides:
mutation_mode: alltransport:
type: streamable_http
endpoint: https://api.production.com/graphql
operations:
source: manifest
path: ./persisted-query-manifest.json
graphos:
apollo_key: ${env.APOLLO_KEY}
apollo_graph_ref: ${env.APOLLO_GRAPH_REF}
headers:
Authorization: "Bearer ${env.API_TOKEN}"
health_check:
enabled: truetransport:
type: streamable_http
address: 0.0.0.0
port: 8000
endpoint: ${env.GRAPHQL_ENDPOINT}
graphos:
apollo_key: ${env.APOLLO_KEY}
apollo_graph_ref: ${env.APOLLO_GRAPH_REF}
health_check:
enabled: true