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

# Using npm
npm install -g @apollo/mcp-server

# Or run directly with npx
npx @apollo/mcp-server

Step 2: Configure

Create mcp.yaml in your project root:

# mcp.yaml
endpoint: https://api.example.com/graphql
schema:
  type: local
  path: ./schema.graphql
operations:
  type: local
  paths:
    - ./operations/**/*.graphql
introspection:
  enabled: true

Step 3: Connect

Add to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

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

Claude Code (.mcp.json):

{
  "mcpServers": {
    "graphql-api": {
      "command": "npx",
      "args": ["@apollo/mcp-server", "--config", "./mcp.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:
  type: local
  paths:
    - ./operations/**/*.graphql

# 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:
  type: collection
  id: your-collection-id

Use GraphOS Studio to manage operations collaboratively.

3. Persisted Queries

operations:
  type: 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
• Prefer introspection.enabled: false in production
• Set introspection.mutationMode: prompt 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:
  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:

introspection:
  mutationMode: allowed   # Execute directly
  mutationMode: prompt    # Require confirmation (default)
  mutationMode: disabled  # Block all mutations

Common Patterns

GraphOS Cloud Schema

schema:
  type: uplink
graphos:
  key: ${APOLLO_KEY}
  graph_ref: my-graph@production

Local Development

endpoint: http://localhost:4000/graphql
schema:
  type: local
  path: ./schema.graphql
introspection:
  enabled: true
  mutationMode: allowed

Production Setup

endpoint: https://api.production.com/graphql
schema:
  type: uplink
operations:
  type: manifest
  path: ./persisted-query-manifest.json
introspection:
  enabled: false

Ground Rules

• ALWAYS configure authentication before exposing to AI agents
• ALWAYS use mutationMode: prompt 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