apollo-mcp-server

Apollo MCP サーバーガイド

Apollo MCP サーバーは GraphQL オペレーションを MCP ツールとして公開し、AI エージェントが Model Context Protocol を通じて GraphQL API を操作できるようにします。

クイックスタート

ステップ 1：インストール

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

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

ステップ 2：設定

プロジェクトのルートに 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

サーバーを起動します。

apollo-mcp-server ./config.yaml

MCP エンドポイントは http://127.0.0.1:8000/mcp で利用できます（streamable_http のデフォルトは、アドレスが 127.0.0.1、ポートが 8000 です）。GraphQL エンドポイントのデフォルトは http://localhost:4000/ です。API が別の場所で稼働している場合は、endpoint キーで上書きしてください。

サーバーは設定ファイルの変更を監視し、設定が更新されると自動的に再起動します。

ステップ 3：接続

MCP クライアントの設定に追加します。

Streamable HTTP（推奨）：

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（クライアントがサーバーを直接起動）：

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

組み込みツール

ツール	用途	使用するタイミング
introspect	スキーマの型を詳しく調べる	型定義、フィールド、関連を確認する場合
search	スキーマ内の型を検索する	特定の型やフィールドを探す場合
validate	オペレーションの有効性を確認する	オペレーションを実行する前
execute	その場で GraphQL オペレーションを実行する	テストや単発のクエリを行う場合
explorer	Apollo Explorer でオペレーションを開く	Explorer の URL を生成する場合（GraphOS グラフ参照が必要）

カスタムツールの定義

MCP ツールは GraphQL オペレーションから作成します。

1. オペレーションファイル（推奨）

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

2. オペレーションコレクション

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

3. 永続化クエリ

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

4. スキーマイントロスペクション

operations:
  source: introspect

5. GraphOS Uplink

operations:
  source: uplink

リファレンスファイル

• ツール - イントロスペクションツール、Explorer、minify 記法、ツールのアノテーション
• 設定 - すべての設定オプション
• 認証 - OAuth 2.1、スコープ、トークン検証、オペレーションごとのスコープ
• Rhai スクリプト - ライフサイクルフックと組み込み関数
• MCP プロンプト - 再利用可能なプロンプトテンプレート
• テレメトリ - OpenTelemetry のメトリクス、トレース、ダッシュボード
• トラブルシューティング - よくある問題と解決方法

重要なルール

セキュリティ

セキュリティ：機密性の高いオペレーション。 AI エージェントに公開する前に認証を設定してください。API キーには headers を、ユーザー単位のアクセスには OAuth を使用してください。

• 本番環境ではイントロスペクションツールを無効にしてください（デフォルトでは無効です）
• overrides.mutation_mode を使用して、ミューテーションの公開を制御してください

認証

# Static header
headers:
  Authorization: "Bearer ${env.API_TOKEN}"

# Dynamic header forwarding
forward_headers:
  - x-tenant-id

# OAuth (streamable_http transport)
transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
    scopes:
      - read
    scope_mode: require_all

スキーマソース

# Local file
schema:
  source: local
  path: ./schema.graphql

# Federated graphs (uplink)
schema:
  source: uplink

# Non-federated graphs (graphos)
schema:
  source: graphos

ミューテーション

overrides.mutation_mode でミューテーションの動作を制御します。

モード	定義済みミューテーション	その場でのミューテーション（execute）
none	スキップ	拒否
explicit	公開	拒否
all	公開	許可

トークンの最適化

トークン使用量を削減するには、minification を有効にします。

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

よくあるパターン

GraphOS クラウドスキーマ

graphos:
  apollo_key: ${env.APOLLO_KEY}
  apollo_graph_ref: my-graph@production
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs

ローカル開発

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

本番環境のセットアップ

transport:
  type: streamable_http
  auth:
    servers:
      - https://auth.example.com
    audiences:
      - https://api.example.com
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}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true
telemetry:
  exporters:
    metrics:
      otlp:
        endpoint: https://your-metrics-endpoint
        protocol: http/protobuf
    tracing:
      otlp:
        endpoint: https://your-traces-endpoint
        protocol: http/protobuf

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}
schema:
  source: uplink # federated graphs; use graphos for non-federated graphs
health_check:
  enabled: true

基本ルール

• AI エージェントに公開する前に、必ず認証を設定してください
• 共有環境では、必ず mutation_mode: explicit または mutation_mode: none を使用してください
• 書き込みアクセス可能なイントロスペクションツールを、本番データに対して決して公開しないでください
• auth をトップレベルに配置しないでください。必ず transport の下にネストしてください
• 動作の予測可能性を高めるため、その場での実行よりオペレーションファイルを優先してください
• リモート環境や複数クライアントのデプロイでは、streamable_http トランスポートを優先してください
• フェデレーションされていないグラフには schema.source: graphos を使用してください（Uplink が提供するのはフェデレーショングラフのみです）
• MCP クライアントがサーバープロセスを直接起動する場合に限り、stdio を使用してください
• チームでのコラボレーションには GraphOS Studio コレクションを使用してください