Index of every page on this site: llms.txt
All skills
apollographql avatar

/apollo-mcp-server

@9dda139 official
by Apollo GraphQLapollographql/skills134 stars
14
Run it yourself

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, explorer), (4) configuring authentication, CORS, health checks, or telemetry, (5) writing Rhai scripts for request lifecycle hooks, (6) defining MCP prompts, (7) troubleshooting MCP server connectivity or tool execution issues, (8) building MCP Apps for interactive UI experiences, (9) deploying Apollo MCP Server to production.

Use this Skill: https://skilld.dev/gh/apollographql/skills/apollo-mcp-server

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesdeploy.md

≈1.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Deployment

Installation

Installer script

# Linux / macOS
curl -sSL https://mcp.apollo.dev/download/nix/latest | sh

# Windows
iwr 'https://mcp.apollo.dev/download/win/latest' | iex

Build from source

cargo install --locked apollo-mcp-server

--locked builds with the same dependency versions tested for the release.

Deployment options

Apollo GraphOS Operator (Kubernetes)

Use the Apollo GraphOS Operator to deploy Apollo MCP Server on Kubernetes. The operator manages the Deployment, Service, ConfigMap, and an ephemeral graph API key Secret.

Requirements:

  • Apollo GraphOS Operator v1.5.0 or later
  • Apollo GraphOS Developer, Standard, or Enterprise plan

The operator forces transport.stateful_mode: false, so no session-affinity configuration is needed. Its plain Kubernetes Service works without special load balancer setup.

Scale with spec.replicas on the McpServer resource, or attach a Kubernetes HorizontalPodAutoscaler directly to it. The operator exposes a scale subresource, so the McpServer itself can be the autoscaling target.

Apollo Runtime Container (non-Kubernetes)

The all-in-one Apollo Runtime Container includes Apollo Router and Apollo MCP Server in a single image. Both port 4000 (GraphQL) and port 8000 (MCP) are exposed.

docker run \
  -p 4000:4000 \
  -p 8000:8000 \
  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
  --env APOLLO_KEY="<your-graph-api-key>" \
  --env MCP_ENABLE=1 \
  -v /path/to/config:/config/mcp_config.yaml \
  --rm \
  ghcr.io/apollographql/apollo-runtime:latest

This fetches the schema from GraphOS, starts the router, and enables the MCP endpoint at /mcp. By default it uses GraphOS-managed persisted queries for MCP tools.

Benefits:

  • Single container to deploy and monitor
  • Co-located Router and MCP Server for optimized performance
  • Scale both GraphQL and MCP together as one unit

Standalone Apollo MCP Server container

Use the standalone container when you already have a GraphQL API running elsewhere.

The container expects schema and operation files in the /data directory and serves Streamable HTTP on port 8000.

# mcp_config.yaml
endpoint: https://your-graphql-api.example.com/
operations:
  source: local
  paths:
    - /data/operations/
schema:
  source: local
  path: /data/api.graphql
docker run \
  -it --rm \
  -p 8000:8000 \
  -v ./mcp_config.yaml:/config.yaml \
  -v ./data:/data \
  --pull always \
  ghcr.io/apollographql/apollo-mcp-server:latest /config.yaml

Scale Apollo MCP Server independently of your GraphQL API for fine-tuned resource allocation.

Local development with rover dev

Use rover dev to develop locally with both GraphQL and MCP running together. See the Rover CLI documentation.

When to choose which option

Scenario Recommended option Why
Kubernetes with GraphOS-managed graph Apollo GraphOS Operator Manages the full resource lifecycle automatically
New GraphQL + MCP deployment (non-K8s) Apollo Runtime Container Single container, optimized performance
GraphOS-managed graph (non-K8s) Apollo Runtime Container Automatic schema and persisted query sync
Adding MCP to an existing GraphQL API Standalone container Connects to your existing endpoint
Local development rover dev Runs both GraphQL and MCP locally

Load balancing and session affinity

Clients that negotiate MCP protocol 2026-07-28 or later are always sessionless and need no session affinity. Older protocol versions are stateful and require sticky sessions.

When an older client initializes a session, it receives a session identifier through the mcp-session-id header. Configure your load balancer to route all requests sharing the same mcp-session-id to the same backend instance.

Load balancers that support header-based session affinity:

  • Nginx
  • HAProxy
  • Envoy / Istio

Cloud load balancers such as AWS ALB and Google Cloud Load Balancer do not support header-based session affinity.

Stateless mode

Disable session state to allow horizontal scaling without session affinity, even for older protocol clients:

transport:
  type: streamable_http
  stateful_mode: false

In stateless mode, each request is an independent HTTP POST with no session ID exchange. Unsolicited tool-change notifications are unavailable for older clients in this mode. Clients on 2026-07-28 or later are always sessionless regardless of this setting.

Production checklist

After deploying, configure:

  1. Health checks for liveness and readiness probes
  2. CORS for browser-based MCP clients
  3. Authentication for production security
  4. Telemetry for observability

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert23d5 checks · Risk HIGH
  • Gen Agent Trust Hub23d

    This skill provides a comprehensive guide for using the Apollo MCP Server. It includes official installation commands that download and execute scripts from the vendor's domain. The skill also processes external GraphQL data, such as schemas and operations, which presents a surface for indirect prompt injection if these sources are attacker-controlled. Additionally, it documents the use of Rhai scripting for runtime customization of server behavior.

  • Socket23d

    No alerts

  • Snyk23d

    Risk: LOW · No issues

  • Runlayer8mo

    2/4 files flagged

  • ZeroLeaks7mo

    1 finding · Score: 82/100

Signed by skilld at 9dda139. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 4 weeks ago
What it can do
Runs commands
compatibility
Works with Claude Code, Claude Desktop, Cursor.
metadata
{
  "author": "apollographql",
  "version": "1.3.0"
}
All 1 allowed tools
Bash(rover:*) Bash(npx:*) Read Write Edit Glob Grep
  • MCP
  • API
  • graphql
  • apollo
  • introspection
  • schema
  • claude
  • cursor
  • authentication

README badge

README badge for apollographql/skills/apollo-mcp-server

Exposes GraphQL operations as MCP tools, allowing AI agents to query and mutate GraphQL APIs through the Model Context Protocol. Includes introspection tools (search, validate, execute) and supports operation files, GraphOS collections, and persisted queries with configurable authentication and mutation controls.

Generated from the current SKILL.md.

What transport types does Apollo MCP Server support?
Apollo MCP Server supports streamable_http (recommended for remote and multi-client deployments) and stdio (for clients that launch the server directly). Streamable_http defaults to address 127.0.0.1 and port 8000.
Can I use this with Claude Desktop and Claude Code?
Yes. Apollo MCP Server is compatible with Claude Desktop, Claude Code, and Cursor. Configuration differs slightly: Claude Desktop uses claude_desktop_config.json, while Claude Code uses .mcp.json or the claude mcp add command.
How do I define custom tools from GraphQL operations?
Create GraphQL operation files in a directory (one operation per file) and configure the operations source as local with the directory path. Each named operation automatically becomes an MCP tool. You can also use GraphOS Studio collections or persisted query manifests.
What security settings should I enable for production?
Set mutation_mode to explicit or none (default), use headers configuration for API keys, enable health checks, disable introspection tools, and authenticate requests with Bearer tokens or OAuth. Use persisted queries instead of ad-hoc operations.
What are the four built-in introspection tools?
introspect (explore schema types), search (find types in schema), validate (check operation validity), and execute (run ad-hoc GraphQL operations). All four are disabled by default and must be explicitly enabled in config.yaml.

Generated from the current SKILL.md. These answers refresh after source changes.