Agent skill

apollo-mcp-server

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.

View SKILL.md on GitHub Repository
Stars 45
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/apollographql/skills/tree/main/skills/apollo-mcp-server

Metadata

Additional technical details for this skill

author
apollographql
version
1.1.1

SKILL.md

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

bash
# 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:

yaml
# config.yaml
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:

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

Step 3: Connect

Add to your MCP client configuration:

Streamable HTTP (recommended):

Claude Desktop (claude_desktop_config.json):

json
{
  "mcpServers": {
    "graphql-api": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

Claude Code:

bash
claude mcp add graphql-api -- npx mcp-remote http://127.0.0.1:8000/mcp

Stdio (client launches the server directly):

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

json
{
  "mcpServers": {
    "graphql-api": {
      "command": "./apollo-mcp-server",
      "args": ["./config.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)

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

Each file must contain exactly one operation. Each named operation becomes an MCP tool.

graphql
# operations/GetUser.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}
graphql
# operations/CreateUser.graphql
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
  }
}

2. Operation Collections

yaml
operations:
  source: collection
  id: your-collection-id

Use GraphOS Studio to manage operations collaboratively.

3. Persisted Queries

yaml
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 (they are disabled by default)
  • Set overrides.mutation_mode: explicit to require confirmation for mutations

Authentication

yaml
# 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:

yaml
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:

yaml
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

yaml
# 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

yaml
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

yaml
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

yaml
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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

apollographql/skills

apollo-client

Guide for building React applications with Apollo Client 4.x. Use this skill when: (1) setting up Apollo Client in a React project, (2) writing GraphQL queries or mutations with hooks, (3) configuring caching or cache policies, (4) managing local state with reactive variables, (5) troubleshooting Apollo Client errors or performance issues.

45 3
Explore
apollographql/skills

apollo-connectors

Guide for integrating REST APIs into GraphQL supergraphs using Apollo Connectors with @source and @connect directives. Use this skill when the user: (1) mentions "connectors", "Apollo Connectors", or "REST Connector", (2) wants to integrate a REST API into GraphQL, (3) references @source or @connect directives, (4) works with files containing "# Note to AI Friends: This is an Apollo Connectors schema".

45 3
Explore
apollographql/skills

apollo-server

Guide for building GraphQL servers with Apollo Server 5.x. Use this skill when: (1) setting up a new Apollo Server project, (2) writing resolvers or defining GraphQL schemas, (3) implementing authentication or authorization, (4) creating plugins or custom data sources, (5) troubleshooting Apollo Server errors or performance issues.

45 3
Explore
apollographql/skills

apollo-kotlin

Guide for building applications with Apollo Kotlin, the GraphQL client library for Android and Kotlin. Use this skill when: (1) setting up Apollo Kotlin in a Gradle project for Android, Kotlin/JVM, or KMP, (2) configuring schema download and codegen for GraphQL services, (3) configuring an `ApolloClient` with auth, interceptors, and caching, (4) writing queries, mutations, or subscriptions,

45 3
Explore
apollographql/skills

rust-best-practices

Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when: (1) writing new Rust code or functions, (2) reviewing or refactoring existing Rust code, (3) deciding between borrowing vs cloning or ownership patterns, (4) implementing error handling with Result types, (5) optimizing Rust code for performance, (6) writing tests or documentation for Rust projects.

45 3
Explore
apollographql/skills

rover

Guide for using Apollo Rover CLI to manage GraphQL schemas and federation. Use this skill when: (1) publishing or fetching subgraph/graph schemas, (2) composing supergraph schemas locally or via GraphOS, (3) running local supergraph development with rover dev, (4) validating schemas with check and lint commands, (5) configuring Rover authentication and environment.

45 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results