apollo-mcp-server

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

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 - Introspection tools, explorer, minify notation, tool annotations
• Configuration - All configuration options including tasks and caching
• Authentication - OAuth 2.1, scopes, token validation, rate limiting, per-operation scopes
• Rhai Scripting - Lifecycle hooks and built-in functions
• MCP Prompts - Reusable prompt templates
• MCP Apps - Interactive mini-applications for MCP-compatible hosts
• Deployment - Docker, Kubernetes, Apollo Runtime Container, scaling
• Error Handling - Protocol errors, tool errors, GraphQL error mapping
• Best Practices - Security guidance, mutation gating, tool poisoning, token passthrough
• Telemetry - OpenTelemetry metrics, traces, and dashboards
• Troubleshooting - 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:

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