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.

License 许可
MIT
最近更新
2026-05-22
Stars
★ 0
Forks
0

01 前言 Front Matter

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

02 资源文件 3

03 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

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

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

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

{
  "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):

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.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)

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

04 同仓库更多 Skills

julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

simpy

Process-based discrete-event simulation framework in Python. Use this skill when building simulations of systems with processes, queues, resources, and time-based events such as manufacturing systems, service operations, network traffic, logistics, or any system where entities interact with shared resources over time.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

shopify-expert

Builds and debugs Shopify themes (.liquid files, theme.json, sections), develops custom Shopify apps (shopify.app.toml, OAuth, webhooks), and implements Storefront API integrations for headless storefronts. Use when building or customizing Shopify themes, creating Hydrogen or custom React storefronts, developing Shopify apps, implementing checkout UI extensions or Shopify Functions, optimizing performance, or integrating third-party services. Invoke for Liquid templating, Storefront API, app development, checkout customization, Shopify Plus features, App Bridge, Polaris, or Shopify CLI workflows.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

shap

Model interpretability and explainability using SHAP (SHapley Additive exPlanations). Use this skill when explaining machine learning model predictions, computing feature importance, generating SHAP plots (waterfall, beeswarm, bar, scatter, force, heatmap), debugging models, analyzing model bias or fairness, comparing models, or implementing explainable AI. Works with tree-based models (XGBoost, LightGBM, Random Forest), deep learning (TensorFlow, PyTorch), linear models, and any black-box model.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

shadcn-ui

Deep expertise on shadcn/ui component library including installation, customization, theming, and accessibility patterns. Use when building UI with shadcn/ui components, integrating Radix UI primitives, configuring Tailwind CSS v4 themes, or implementing dark mode. Covers Next.js App Router, Pages Router, and Vite setups.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

seoul-subway-arrival

Look up Seoul real-time subway arrival information with the official Seoul Open Data API. Use when the user asks when a train arrives, which trains are approaching a station, or how crowded Seoul subway timing looks right now.

★ 0
julio211916
julio211916/TlantiCAD-Studio-V0.1-alpha

seo-optimization

Comprehensive 7-phase SEO optimization workflow covering technical SEO auditing, keyword research strategy, on-page optimization, content SEO and E-E-A-T, structured data implementation, link building, and AI search optimization. Use when auditing search engine visibility, diagnosing ranking issues, implementing schema markup, conducting keyword research, optimizing content for E-E-A-T signals, or adapting for AI-driven search (AI Overviews, SGE).

★ 0