Skills

Skill 6 of 15

Apollo MCP Server

Guide for using Apollo MCP Server to connect AI agents with GraphQL APIs.

2 minutes · 497 words · 27 sections

Install

$ npx skills add apollographql/skills --skill apollo-mcp-server

$ npx skills add apollographql/skills

» /plugin marketplace add apollographql/skills

The first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.

Apollo MCP Server Guide

Apollo MCP Server exposes GraphQL operations as MCP tools, enabling AI agents to interact with GraphQL APIs through the Model Context Protocol.

Quick Start

Step 1: Install

# Linux / MacOS
curl -sSL https://mcp.apollo.dev/download/nix/latest | sh

# Windows
iwr 'https://mcp.apollo.dev/download/win/latest' | iex

Step 2: Configure

Create config.yaml in your project root:

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: true

Start the server:

apollo-mcp-server ./config.yaml

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.

The server watches the config file for changes and automatically restarts with updated configuration.

Step 3: Connect

Add to your MCP client configuration:

Streamable HTTP (recommended):

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "graphql-api": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

Claude Code:

claude mcp add graphql-api -- npx mcp-remote http://127.0.0.1:8000/mcp

Stdio (client launches the server directly):

{
  "mcpServers": {
    "graphql-api": {
      "command": "./apollo-mcp-server",
      "args": ["./config.yaml"]
    }
  }
}

Built-in 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
`explorer`	Open operation in Apollo Explorer	Generate Explorer URLs (requires GraphOS graph ref)

Defining Custom Tools

MCP tools are created from GraphQL operations:

1. Operation Files (Recommended)

operations:
  source: local
  paths:
    - ./operations/

2. Operation Collections

operations:
  source: collection
  id: your-collection-id

3. Persisted Queries

operations:
  source: manifest
  path: ./persisted-query-manifest.json

4. Schema Introspection

operations:
  source: introspect

5. GraphOS Uplink

operations:
  source: uplink

Reference Files

Tools (opens in a new tab) - Introspection tools, explorer, minify notation, tool annotations
Configuration (opens in a new tab) - All configuration options including tasks and caching
Authentication (opens in a new tab) - OAuth 2.1, scopes, token validation, rate limiting, per-operation scopes
Rhai Scripting (opens in a new tab) - Lifecycle hooks and built-in functions
MCP Prompts (opens in a new tab) - Reusable prompt templates
MCP Apps (opens in a new tab) - Interactive mini-applications for MCP-compatible hosts
Deployment (opens in a new tab) - Docker, Kubernetes, Apollo Runtime Container, scaling
Error Handling (opens in a new tab) - Protocol errors, tool errors, GraphQL error mapping
Best Practices (opens in a new tab) - Security guidance, mutation gating, tool poisoning, token passthrough
Telemetry (opens in a new tab) - OpenTelemetry metrics, traces, and dashboards
Troubleshooting (opens in a new tab) - Common issues and solutions

Key Rules

Security

Security: Sensitive operations. Configure authentication before exposing to AI agents. Use headers for API keys, OAuth for user-scoped access.

Disable introspection tools in production (they are disabled by default)
Use overrides.mutation_mode to control mutation exposure

Authentication

# Static header
headers:
  Authorization: "Bearer ${env.API_TOKEN}"

# Dynamic header forwarding
forward_headers:
  - x-tenant-id

# OAuth (streamable_http transport)
transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
    scopes:
      - read
    scope_mode: require_all

Schema Sources

# Local file
schema:
  source: local
  path: ./schema.graphql

# Federated graphs (uplink)
schema:
  source: uplink

# Non-federated graphs (graphos)
schema:
  source: graphos

Mutations

Control mutation behavior via overrides.mutation_mode:

Mode	Predefined mutations	Ad hoc mutations (`execute`)
`none`	Skipped	Rejected
`explicit`	Exposed	Rejected
`all`	Exposed	Allowed

MCP Apps

Build interactive UI experiences inside MCP Apps-compatible hosts (e.g., ChatGPT). Define tools with @tool and @prefetch directives on GraphQL operations. Configure the apps directory:

apps:
  path: ./apps

MCP Tasks

Return async task handles for slow GraphQL calls. Clients poll tasks/get for results:

tasks:
  enabled: true
  detach_after_ms: 1000

Token Optimization

Enable minification to reduce token usage:

introspection:
  introspect:
    minify: true
  search:
    minify: true

Common Patterns

GraphOS Cloud Schema

graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs

Local Development

transport:
  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: all

Production Setup

transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
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}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true
telemetry:
  exporters:
    metrics:
      otlp:
        endpoint: https://your-metrics-endpoint
        protocol: http/protobuf
    tracing:
      otlp:
        endpoint: https://your-traces-endpoint
        protocol: http/protobuf

Docker

transport:
  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}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true

Ground Rules

ALWAYS configure authentication before exposing to AI agents
ALWAYS use mutation_mode: explicit or mutation_mode: none in shared environments
ALWAYS review overrides.required_scopes keys after tool changes
NEVER expose introspection tools with write access to production data
NEVER place auth at the top level — it must be nested under transport
NEVER assume mutation_mode provides per-invocation approval (it is a configuration gate)
PREFER operation files over ad-hoc execute for predictable behavior
PREFER streamable_http transport for remote and multi-client deployments
PREFER contract variants when using persisted queries or introspection with GraphOS
USE schema.source: graphos for non-federated graphs (uplink only serves federated graphs)
USE stdio only when the MCP client launches the server process directly
USE GraphOS Studio collections for team collaboration
USE disable_auth_token_passthrough: true when your API does not need the caller’s token

About this skill

Trigger

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, explorer), (4) configuring authentication, CORS, health checks, or telemetry, (5) writing Rhai scripts for request lifecycle hooks, (6) defining MCP prompts, (7) troubleshooting MCP server connectivity or tool execution issues, (8) building MCP Apps for interactive UI experiences, (9) deploying Apollo MCP Server to production.

The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.

Allowed tools: Bash(rover:*)Bash(npx:*)ReadWriteEditGlobGrep
Compatibility: Works with Claude Code, Claude Desktop, Cursor.
Licence: MIT
Source: skills/apollo-mcp-server/SKILL.md

Colophon for this issue

Colophon

How this issue was made

Source

github.com/apollographql/skills, branch main, last pushed 6 November 2026.

Licence

MIT — the text of every skill is reproduced unmodified, frontmatter included, under the upstream licence.

Discovery

15 skills found by walking the repository tree for SKILL.md, not by matching a directory convention. One layout observed: skills/*/SKILL.md.

Issue colours

Resolved from a deterministic hash of the owner name. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.

Heading repairs

1 repair applied to this skill so the document has one h1 and no skipped levels:

Shifted “27 headings” from h1 to h2 so the skill title is the only h1.

Spec compliance

Every skill satisfies the Agent Skills specification’s frontmatter rules.

Images

Images inside a skill come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.

Marketplace

A plugin manifest is published at .claude-plugin/marketplace.json by Apollo GraphQL, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree.

Signal

Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.

Agent surfaces

The whole issue is available as one markdown document at /apollographql/skills.md, and each skill at its own .md URL.

Publication

Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.

Apollo MCP Server Guide

Apollo MCP Server exposes GraphQL operations as MCP tools, enabling AI agents to interact with GraphQL APIs through the Model Context Protocol.

Quick Start

Step 1: Install

# Linux / MacOS
curl -sSL https://mcp.apollo.dev/download/nix/latest | sh

# Windows
iwr 'https://mcp.apollo.dev/download/win/latest' | iex

Step 2: Configure

Create config.yaml in your project root:

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: true

Start the server:

apollo-mcp-server ./config.yaml

The server watches the config file for changes and automatically restarts with updated configuration.

Step 3: Connect

Add to your MCP client configuration:

Streamable HTTP (recommended):

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "graphql-api": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

Claude Code:

claude mcp add graphql-api -- npx mcp-remote http://127.0.0.1:8000/mcp

Stdio (client launches the server directly):

{
  "mcpServers": {
    "graphql-api": {
      "command": "./apollo-mcp-server",
      "args": ["./config.yaml"]
    }
  }
}

Built-in 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
`explorer`	Open operation in Apollo Explorer	Generate Explorer URLs (requires GraphOS graph ref)

Defining Custom Tools

MCP tools are created from GraphQL operations:

1. Operation Files (Recommended)

operations:
  source: local
  paths:
    - ./operations/

2. Operation Collections

operations:
  source: collection
  id: your-collection-id

3. Persisted Queries

operations:
  source: manifest
  path: ./persisted-query-manifest.json

4. Schema Introspection

operations:
  source: introspect

5. GraphOS Uplink

operations:
  source: uplink

Reference Files

Tools (opens in a new tab) - Introspection tools, explorer, minify notation, tool annotations
Configuration (opens in a new tab) - All configuration options including tasks and caching
Authentication (opens in a new tab) - OAuth 2.1, scopes, token validation, rate limiting, per-operation scopes
Rhai Scripting (opens in a new tab) - Lifecycle hooks and built-in functions
MCP Prompts (opens in a new tab) - Reusable prompt templates
MCP Apps (opens in a new tab) - Interactive mini-applications for MCP-compatible hosts
Deployment (opens in a new tab) - Docker, Kubernetes, Apollo Runtime Container, scaling
Error Handling (opens in a new tab) - Protocol errors, tool errors, GraphQL error mapping
Best Practices (opens in a new tab) - Security guidance, mutation gating, tool poisoning, token passthrough
Telemetry (opens in a new tab) - OpenTelemetry metrics, traces, and dashboards
Troubleshooting (opens in a new tab) - Common issues and solutions

Key Rules

Security

Security: Sensitive operations. Configure authentication before exposing to AI agents. Use headers for API keys, OAuth for user-scoped access.

Disable introspection tools in production (they are disabled by default)
Use overrides.mutation_mode to control mutation exposure

Authentication

# Static header
headers:
  Authorization: "Bearer ${env.API_TOKEN}"

# Dynamic header forwarding
forward_headers:
  - x-tenant-id

# OAuth (streamable_http transport)
transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
    scopes:
      - read
    scope_mode: require_all

Schema Sources

# Local file
schema:
  source: local
  path: ./schema.graphql

# Federated graphs (uplink)
schema:
  source: uplink

# Non-federated graphs (graphos)
schema:
  source: graphos

Mutations

Control mutation behavior via overrides.mutation_mode:

Mode	Predefined mutations	Ad hoc mutations (`execute`)
`none`	Skipped	Rejected
`explicit`	Exposed	Rejected
`all`	Exposed	Allowed

MCP Apps

Build interactive UI experiences inside MCP Apps-compatible hosts (e.g., ChatGPT). Define tools with @tool and @prefetch directives on GraphQL operations. Configure the apps directory:

apps:
  path: ./apps

MCP Tasks

Return async task handles for slow GraphQL calls. Clients poll tasks/get for results:

tasks:
  enabled: true
  detach_after_ms: 1000

Token Optimization

Enable minification to reduce token usage:

introspection:
  introspect:
    minify: true
  search:
    minify: true

Common Patterns

GraphOS Cloud Schema

graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs

Local Development

transport:
  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: all

Production Setup

transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
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}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true
telemetry:
  exporters:
    metrics:
      otlp:
        endpoint: https://your-metrics-endpoint
        protocol: http/protobuf
    tracing:
      otlp:
        endpoint: https://your-traces-endpoint
        protocol: http/protobuf

Docker

transport:
  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}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true

Ground Rules

ALWAYS configure authentication before exposing to AI agents
ALWAYS use mutation_mode: explicit or mutation_mode: none in shared environments
ALWAYS review overrides.required_scopes keys after tool changes
NEVER expose introspection tools with write access to production data
NEVER place auth at the top level — it must be nested under transport
NEVER assume mutation_mode provides per-invocation approval (it is a configuration gate)
PREFER operation files over ad-hoc execute for predictable behavior
PREFER streamable_http transport for remote and multi-client deployments
PREFER contract variants when using persisted queries or introspection with GraphOS
USE schema.source: graphos for non-federated graphs (uplink only serves federated graphs)
USE stdio only when the MCP client launches the server process directly
USE GraphOS Studio collections for team collaboration
USE disable_auth_token_passthrough: true when your API does not need the caller’s token

About this skill

Trigger

Colophon

Appendix 6.1–6.11

ReferencesMarkdown · 11 files

About this skill

Trigger

Colophon

Appendix 6.1–6.11

ReferencesMarkdown · 11 files