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.

1. Operation Collections operations: type: collection id: your-collection-id

Use GraphOS Studio to manage operations collaboratively.

1. 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