GraphQLスキーマをAIエージェントのツールに変換する — 最小限の手順でバックエンド変更ゼロの自然言語APIアクセスを実現するMCP活用法

9月3日、Apollo GraphQLが「How to Build AI Agents Using Your GraphQL Schema」と題した記事を公開した。この記事では、既存のGraphQLスキーマを活用してAIエージェントをAPIに接続する実装手順について詳しく紹介されている。イントロスペクションによるスキーマ取得やoperationファイルの作成といった準備作業は必要になるものの、バックエンドのコード変更は一切不要で実現できる点が特徴だ。

GraphQLスキーマがAIエージェントのツール定義になる

AIエージェントを既存のシステムに接続する際、最大の課題はLLM（大規模言語モデル）の自然言語推論とAPIの構造化インターフェースをどう橋渡しするかだ。GraphQLはその答えに近い位置にある。

GraphQLの強力な型システムとビルトインのイントロスペクション機能により、エージェントはAPIに対して「このAPIで何ができるか」を実行時に問い合わせられる。エンドポイントの挙動を推測する必要もなく、古くなったドキュメントに頼る必要もない。スキーマそのものが、利用可能なすべての操作・入力・レスポンス形状を機械可読な形で記述している。

RESTと比較した場合、REST APIをエージェントに接続するにはOpenAPI仕様書の整備やカスタムのツール記述が別途必要になることが多い。GraphQLはスキーマ自体がその役割を果たすため、ツール定義の二重管理が生じにくい。

これをAIエージェントから利用可能にする標準が**Model Context Protocol（MCP）**だ。MCPはAnthropicが策定したオープンプロトコルで、エージェントが外部ツールを発見・呼び出す方法を標準化する。MCP互換のAIシステムであればカスタムの統合コードなしにどのMCPサーバーにも接続できる。

Apollo MCP ServerはこのMCPをGraphQL向けに実装したもので、既存のGraphQL operationをそのままAIが呼び出せるMCPツールに変換する。バックエンドへの変更は一切不要だ。なお、Apollo MCP ServerはApollo GraphOSのマネージドサービスとしても利用可能で、その場合はDocker運用なしにクラウド上で同等の機能を提供できる。

実装の全体像：7ステップ

記事では、世界の国情報を提供する公開GraphQL API（https://countries.trevorblades.com/graphql）を例に、AIエージェントとの接続手順をステップバイステップで解説している。AIクライアントにはAnthropicのClaude Code（執筆時点でベータ提供中のCLIベース開発支援ツール）を使用する。

必要なものはDockerとClaude Code CLIのみ。コード一式はGitHubリポジトリでも公開されている。

ステップ1〜3：スキーマ取得とツール定義

まずイントロスペクションクエリでAPIのスキーマ全体を取得する。この取得作業自体は一度行えばよいが、スキーマが更新された際には再取得が必要になる点は留意しておきたい。

query IntrospectionQuery {
  __schema {
    queryType { name }
    types {
      name
      kind
      fields {
        name
        type { name kind }
      }
    }
  }
}

取得した情報をもとにapi.graphqlとしてスキーマファイルを保存する（Apollo Studio Sandboxから直接コピーする方法も紹介されている）。

次に、エージェントが呼び出せるツールはGraphQL operationの定義がそのまま対応する。operations/ディレクトリに.graphqlファイルを置くだけでよい。

# operations/GetCountriesByContinent.graphql
query GetCountriesByContinent($continentCode: String!) {
  countries(filter: { continent: { eq: $continentCode } }) {
    code
    name
    capital
    emoji
    currency
    languages {
      code
      name
    }
  }
}

各operationの名前・パラメータ・返却フィールドがそのままツールの仕様としてエージェントに伝わる。エージェントはこの情報をもとに「どのツールをどんな引数で呼ぶか」を判断する。operationファイルは必要な操作分だけ用意する必要があるため、スキーマ規模が大きい場合は事前に公開範囲を設計しておくとよい。

ステップ4〜5：サーバー設定とDocker起動

config.yamlでエンドポイント・スキーマ・operationsの場所を指定する。

endpoint: https://countries.trevorblades.com/graphql
transport:
  type: streamable_http
  port: 5000
operations:
  source: local
  paths:
    - ./operations
schema:
  source: local
  path: ./api.graphql

あとはDockerで起動するだけだ。

docker run \
  -it --rm \
  --name apollo-mcp-server \
  -p 5000:5000 \
  -v $HOME/countries-mcp/config.yaml:/config.yaml \
  -v $HOME/countries-mcp:/data \
  --pull always \
  ghcr.io/apollographql/apollo-mcp-server:latest \
  /config.yaml

起動するとINFO Starting MCP server in Streamable HTTP mode port=5000と表示され、ポート5000でMCPツールが公開される。

ステップ6〜7：Claude Codeへの登録と自然言語クエリ

別ターミナルでClaude Codeにサーバーを登録する。

claude mcp add --transport http countries http://localhost:5000/mcp

これで自然言語での問い合わせが機能する。

> What countries are in North America that start with the letter C?
● countries - GetCountriesByContinent (MCP)(continentCode: "NA")

エージェントが「北米の国一覧を取得する」ツールを自律的に選択し、結果をCで始まる国でフィルタリングして返す。GraphQLクエリを人間が書く必要はない。

ポイント整理と業界文脈

GraphQLスキーマのイントロスペクション機能がエージェントの「ツール発見」を可能にする。RESTのOpenAPI仕様と異なり、スキーマが実装と同期している前提で設計されているため、ツール定義の陳腐化リスクが構造的に低い
MCPがエージェント↔ツール間の通信を標準化し、特定のAIフレームワークへの依存を排除する。今回はClaude Codeを使用しているが、MCP対応クライアントであれば同じサーバーに接続できる
Apollo MCP ServerはGraphQL operationを自動的にMCPツールへ変換する。既存バックエンドへの変更ゼロという点は他のMCPサーバー実装（REST向けや独自プロトコル向け）と比較したときのGraphQL固有の強みであり、型情報・バリデーション・フィールド選択がそのまま引き継がれる
公開するツールの粒度はoperationファイルの単位で制御できるため、エージェントに見せる操作を明示的に絞り込める。スキーマ全体を無制限に公開するわけではない点は、セキュリティ設計上も重要だ
Apollo GraphOSを利用している場合は、マネージド環境でのMCPサーバー運用も選択肢に入る

スキーマ設計のベストプラクティスについてはHow To Make Your Existing GraphQL API AI-Ready With Apollo、複数APIのオーケストレーションについてはHow to Orchestrate Multiple APIs for Your LLM Agentも参照できる。

詳細はHow to Build AI Agents Using Your GraphQL Schemaを参照していただきたい。