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/v1.6.0' | iex

Step 2: Configure

Create config.yaml in your project root:

# config.yaml
endpoint: https://api.example.com/graphql
schema:
  source: local
  path: ./schema.graphql
operations:
  source: local
  paths:
    - ./operations/
introspection:
  introspect:
    enabled: true
  search:
    enabled: true
  validate:
    enabled: true
  execute:
    enabled: true

Step 3: Connect

Add to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

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

Claude Code (.mcp.json):

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

Built-in Tools

Apollo MCP Server provides four introspection tools:

Defining Custom Tools

MCP tools are created from GraphQL operations. Three methods:

1. Operation Files (Recommended)

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

# operations/users.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
  }
}

Each named operation becomes an MCP tool.

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 – Introspection tools and minify notation
• Configuration – All configuration options
• Troubleshooting – 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 (set enabled: false for each tool)
• Set overrides.mutation_mode: explicit to require confirmation for mutations

Authentication

# Static header
headers:
  Authorization: "Bearer ${APOLLO_API_KEY}"

# Dynamic header passthrough
headers:
  X-User-Token:
    from: x-forwarded-token

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
• ! = 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: uplink
graphos:
  apollo_key: ${APOLLO_KEY}
  apollo_graph_ref: my-graph@production

Local Development

endpoint: http://localhost:4000/graphql
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

endpoint: https://api.production.com/graphql
schema:
  source: uplink
operations:
  source: manifest
  path: ./persisted-query-manifest.json
introspection:
  introspect:
    enabled: false
  search:
    enabled: false
  validate:
    enabled: false
  execute:
    enabled: false

Ground Rules

• ALWAYS configure authentication before exposing to AI agents
• ALWAYS use mutation_mode: explicit or mutation_mode: none in shared environments
• NEVER expose introspection tools with write access to production data
• PREFER operation files over ad-hoc execute for predictable behavior
• USE GraphOS Studio collections for team collaboration