/apollo-mcp-server

name: apollo-mcp-server
description: >
  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.
license: MIT
compatibility: Works with Claude Code, Claude Desktop, Cursor.
metadata:
  author: apollographql
  version: "1.1.1"
allowed-tools: Bash(rover:*) Bash(npx:*) Read Write Edit Glob Grep

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:

# 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: 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.

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):**

Claude Desktop (`claude_desktop_config.json`) or Claude Code (`.mcp.json`):

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

Built-in Tools

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 |

Defining Custom Tools

MCP tools are created from GraphQL operations. Three methods:

1. Operation Files (Recommended)

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

Each file must contain exactly one operation. Each named operation becomes an MCP tool.

# 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
  }
}

2. Operation Collections

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

Use GraphOS Studio to manage operations collaboratively.

3. Persisted Queries

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

For production environments with pre-approved operations.

Reference Files

Detailed documentation for specific topics:

• [Tools](references/tools.md) - Introspection tools and minify notation
• [Configuration](references/configuration.md) - All configuration options
• [Troubleshooting](references/troubleshooting.md) - Common issues and solutions

Key Rules

Security

• **Never expose sensitive operations** without authentication
• Use `headers` configuration for API keys and tokens
• Disable introspection tools in production (they are disabled by default)
• Set `overrides.mutation_mode: explicit` to require confirmation for mutations

Authentication

# 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.com

Token Optimization

Enable minification to reduce token usage:

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

Minified output uses compact notation:

• **T** = type, **I** = input, **E** = enum
• **s** = String, **i** = Int, **b** = Boolean, **f** = Float, **d** = ID
• **!** = required, **[]** = list

Mutations

Control mutation behavior via the `overrides` section:

overrides:
  mutation_mode: all       # Execute mutations directly
  # mutation_mode: explicit  # Require explicit confirmation
  # mutation_mode: none      # Block all mutations (default)

Common Patterns

GraphOS Cloud Schema

# schema.source defaults to uplink — can be omitted when graphos is configured
graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production

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