Guide du serveur Apollo MCP

Apollo MCP Server expose les opérations GraphQL en tant qu'outils MCP, permettant aux agents IA d'interagir avec les API GraphQL via le Model Context Protocol.

Démarrage rapide

Étape 1 : Installation

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

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

Étape 2 : Configuration

Créez config.yaml à la racine de votre projet :

# 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

Démarrez le serveur :

apollo-mcp-server ./config.yaml

Le point de terminaison MCP est disponible à http://127.0.0.1:8000/mcp (valeurs par défaut streamable_http : adresse 127.0.0.1, port 8000). Le point de terminaison GraphQL défaut à http://localhost:4000/ — remplacez-le avec la clé endpoint si votre API s'exécute ailleurs.

Étape 3 : Connexion

Ajoutez à votre configuration client MCP :

Streamable HTTP (recommandé) :

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 (le client lance le serveur directement) :

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

{
  "mcpServers": {
    "graphql-api": {
      "command": "./apollo-mcp-server",
      "args": ["./config.yaml"]
    }
  }
}

Outils intégrés

Apollo MCP Server fournit quatre outils d'introspection :

Définir des outils personnalisés

Les outils MCP sont créés à partir d'opérations GraphQL. Trois méthodes :

1. Fichiers d'opération (recommandé)

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

Chaque fichier doit contenir exactement une opération. Chaque opération nommée devient un outil MCP.

# 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. Collections d'opérations

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

Utilisez GraphOS Studio pour gérer les opérations de manière collaborative.

3. Requêtes persistantes

operations:
  source: manifest
  path: ./persisted-query-manifest.json

Pour les environnements de production avec opérations pré-approuvées.

Fichiers de référence

Documentation détaillée sur des sujets spécifiques :

• Tools - Outils d'introspection et notation minifiée
• Configuration - Toutes les options de configuration
• Troubleshooting - Problèmes courants et solutions

Règles clés

Sécurité

• N'exposez jamais d'opérations sensibles sans authentification
• Utilisez la configuration headers pour les clés API et jetons
• Désactivez les outils d'introspection en production (ils sont désactivés par défaut)
• Définissez overrides.mutation_mode: explicit pour exiger une confirmation pour les mutations

Authentification

# En-tête statique
headers:
  Authorization: "Bearer ${env.API_TOKEN}"

# Transfert d'en-têtes dynamique
forward_headers:
  - x-forwarded-token

# OAuth (transport streamable_http)
transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com/.well-known/openid-configuration
    audiences:
      - https://api.example.com

Optimisation des jetons

Activez la minification pour réduire l'usage des jetons :

introspection:
  introspect:
    minify: true
  search:
    minify: true

La sortie minifiée utilise une notation compacte :

• T = type, I = input, E = enum
• s = String, i = Int, b = Boolean, f = Float, d = ID
• ! = requis, [] = liste

Mutations

Contrôlez le comportement des mutations via la section overrides :

overrides:
  mutation_mode: all       # Exécuter les mutations directement
  # mutation_mode: explicit  # Exiger une confirmation explicite
  # mutation_mode: none      # Bloquer toutes les mutations (défaut)

Motifs courants

Schéma GraphOS Cloud

# schema.source défaut à uplink — peut être omis quand graphos est configuré
graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production

Développement local

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

Configuration de production

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

Règles fondamentales

• TOUJOURS configurer l'authentification avant d'exposer aux agents IA
• TOUJOURS utiliser mutation_mode: explicit ou mutation_mode: none dans les environnements partagés
• JAMAIS exposer les outils d'introspection avec accès en écriture aux données de production
• PRÉFÉRER les fichiers d'opération aux execute ad-hoc pour un comportement prévisible
• PRÉFÉRER le transport streamable_http pour les déploiements distants et multi-clients
• UTILISER stdio uniquement quand le client MCP lance directement le processus serveur
• UTILISER les collections GraphOS Studio pour la collaboration en équipe