Skip to content
Apollo MCP Server

Apollo MCP ServerSkill

by Apollo GraphQL
Released
2 views
v1.1.1
MIT
Repository Docs
markdown Development

Summary

Sets up Apollo MCP Server so an AI agent can call a GraphQL API as MCP tools — defining tools from named operations, or exposing introspect/search/validate/execute for open-ended schemas.

Features

  • Generates MCP tools from named GraphQL operations, one file per tool
  • Optional introspect / search / validate / execute tools for schema exploration
  • stdio and streamable HTTP transports, with header pass-through for auth
  • GraphOS graph ref and apollo key configuration
  • Troubleshooting path for servers that start but register no tools

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: apollo-mcp-server
description: >
  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.
license: MIT
compatibility: Works with Claude Code, Claude Desktop, Cursor.
metadata:
  author: apollographql
  version: "1.1.1"
allowed-tools: Bash(rover:*) Bash(npx:*) Read Write Edit Glob Grep
---

# 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](references/tools.md) - Introspection tools and minify notation
- [Configuration](references/configuration.md) - All configuration options
- [Troubleshooting](references/troubleshooting.md) - 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

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions
npx skills add apollographql/skills --skill apollo-mcp-server

Or copy skills/apollo-mcp-server/ from the repository into your agent's skills directory.

Example Usage

Use the apollo-mcp-server skill to expose our checkout subgraph to Claude Desktop as MCP tools, with one tool per operation in ./operations.

Description

Apollo MCP Server turns a GraphQL API into a set of Model Context Protocol tools, and this is Apollo's official skill for standing one up. It covers the whole path: installing the binary, pointing it at a schema or a GraphOS graph, deciding what the agent is allowed to call, and debugging the connection when a tool does not show up in the client.

Two ways to expose a graph

The skill draws a clear line between the two operating modes, because picking the wrong one is the usual cause of a disappointing agent.

  • Operation-backed tools. Each .graphql file becomes one MCP tool, with its variables as the tool's parameters and its description as the tool's docstring. This is the mode for production: the surface an agent sees is exactly the set of queries you decided to allow, and the schema is never handed over wholesale.
  • Introspection tools. introspect, search, validate and execute let an agent explore an unfamiliar schema and compose its own operations. Useful for development and for internal graphs, and the skill is explicit about the tradeoff in exposure.
What else it handles

Transport choice (stdio for local clients, streamable HTTP for shared deployments), forwarding auth headers from the client to the upstream graph, connecting to GraphOS with an apollo key and graph ref, wiring the server into Claude Code, Claude Desktop or Cursor, and the troubleshooting sequence for the common failures — a server that starts but registers no tools, an operation that will not validate against the schema, or a tool that executes and returns an upstream error.

Details

MIT licensed, version 1.1.1, from the apollographql/skills repository. The skill declares Bash(rover:*), Bash(npx:*), Read, Write, Edit, Glob and Grep as its allowed tools, so it can drive Rover and edit configuration directly rather than dictating steps.

Related Skills

Skill: Inngest Agents

by Inngest

New

Build crash-safe AI agents on AgentKit and step.ai — durable tool calls, human-in-the-loop approval, realtime progress, and when not to reach for an agent loop at all.

Development
2 views

Skill: Inngest Durable Functions

by Inngest

New

Inngest's durable-execution playbook as an agent skill — steps and memoisation, event and cron triggers, idempotency, cancellation, retries and non-retriable errors.

Development
2 views

Skill: Temporal Developer

by Temporal

New

Temporal's official skill for building durable workflows — SDK patterns across seven languages, plus the determinism rules that decide whether a workflow survives a replay.

Development
6 views
Browse all skills →