Labsco
apollographql logo

apollo-mcp-server

★ 91

by apollographql · part of apollographql/skills

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.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#email#devops#git#security
🔌 This skill ships inside the Apollo GraphQL Skills plugin — install the plugin and you also get an MCP server.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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.

Built-in Tools

Apollo MCP Server provides four introspection tools:

ToolPurposeWhen to Use
introspectExplore schema types in detailNeed type definitions, fields, relationships
searchFind types in schemaLooking for specific types or fields
validateCheck operation validityBefore executing operations
executeRun ad-hoc GraphQL operationsTesting or one-off queries

Defining Custom Tools

MCP tools are created from GraphQL operations. Three methods:

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:

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:
  Authorization: "Bearer ${env.API_TOKEN}"
health_check:
  enabled: true

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}
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
  • NEVER expose introspection tools with write access to production data
  • PREFER operation files over ad-hoc execute for predictable behavior
  • PREFER streamable_http transport for remote and multi-client deployments
  • USE stdio only when the MCP client launches the server process directly
  • USE GraphOS Studio collections for team collaboration