ClaudeとApollo GraphOS MCPをつなぐ — Connectorsを書かせる手順

GraphOS MCP Serverは、Apollo GraphQLが提供するホスト型のMCPサーバーです。接続先は https://mcp.apollographql.com で、Claudeには組み込みのコネクタとして用意されています。サインインなしでもApolloの公式ドキュメントとApollo Connectorsの仕様をClaudeに引かせられます。サインインするかAPIキーを渡せば、自分のグラフの状態確認から公開操作まで会話で扱えます。

この記事は、ClaudeとClaude Codeへの接続手順、認証の使い分け、Connectorsを書かせる使い方、そして書き込み系ツールの線引きを扱います。なお、営業データのApollo.ioとは別製品です。そちらはClaudeとApolloを連携する方法にまとめています。

GraphOS MCP Serverでできること

GraphOS MCP Serverのツールは、認証が要るかどうかで二つに分かれます。

ドキュメント系の3つは、役割がはっきり分かれています。

Apollo Connectorsは、REST APIをGraphQLスキーマに宣言的に束ねる仕組みです。スキーマにHTTPメソッド、エンドポイント、レスポンスのマッピングを指示子で書くと、GraphOS Routerがリクエストの発行と変換を引き受けます。Claudeに書かせたいのはまさにこの指示子の部分なので、仕様そのものを取得できるApollo Connectors Specが中心になります。

この名称は2026年7月20日に「GraphOS MCP Tools」から「GraphOS MCP Server」へ変わっています。ディレクトリのURLに graphos-tools が残っているのはそのためです。

認証は3通りで、見える範囲が変わる

接続方法ごとに、エージェントが触れる範囲は次のとおりです。

サインインが推奨されています。APIキーを管理せずに済むからです。APIキーは、クライアントがMCPの認可仕様に対応していない場合や、CIのようにブラウザを開けない環境の代替です。キーは x-api-key ヘッダーで送ります。

グラフ系のツールを認証なしで呼ぶと、呼び出しは失敗します。その際エージェントが、サインインするかAPIキーを渡すよう案内します。

Claudeに接続する手順

ClaudeとClaude Desktopでは、GraphOS MCP Serverが組み込みのコネクタとして使えます。GraphOSへのサインインはブラウザで行うため、APIキーを作る必要はありません。

Claudeはプロンプトに応じてツールを呼ぶ判断を自動で行い、実行前に許可を求めます。この許可の確認が、後述する書き込み系ツールの安全弁になります。Apolloのページに、コネクタを使えるプランの条件は書かれていません。自分の契約で一覧に出るかは、コネクタ一覧で確かめてください。

Claude Codeで追加する

Claude Codeでは、次の1行でHTTP型のサーバーとして追加します。

claude mcp add graphos https://mcp.apollographql.com -t http

ドキュメント系のツールは、追加した直後から使えます。グラフ系を使うときは、/mcp を実行して graphos を選び、「Authenticate」でブラウザのサインイン画面を開きます。サインインして戻り、もう一度 /mcp で認証済みになったことを見ます。

CIなどブラウザを使えない環境では、サーバー追加時にAPIキーを渡します。

claude mcp add graphos https://mcp.apollographql.com -t http \
  --header "x-api-key: YOUR_API_KEY"

YOUR_API_KEY は個人APIキーかグラフAPIキーに置き換えます。キーをシェル履歴やリポジトリに残さない運用が前提です。

GraphOS MCP Serverを使えるのは、Streamable HTTPに対応したクライアントです。ほかのクライアントでも、エンドポイントは同じです。

つながったかを一問で確かめる

接続後は、ドキュメントを引く質問を投げます。Apollo Docsの検索系ツールが動いていれば、答えが返ります。

What is the Apollo Router config file option to control health checks?

グラフに届いているかは、次の一文で確かめます。

Tell me about my graphs.

サインインもAPIキーも無い状態では、グラフ系ツールに認証が要ると案内されます。認証済みなら、アカウントがアクセスできるグラフの一覧が返ります。

Apollo Connectorsを正確に書かせる

ここからが実用の中心です。Connectorsは @connect 指示子でREST APIをスキーマに結びつけます。公式の例では、/products エンドポイントを次の形でマッピングしています。

type Query {
  products: [Product]
    @connect(
      http: { GET: "https://ecommerce.demo-api.apollo.dev/products" }
      selection: """
      $.products {
        id
        name
      }
      """
    )
}

指示子の書式はバージョンで進みます。仕様を記憶に頼って書かせると、古い書式を出しやすい部分です。Apollo Connectors Specを呼ばせれば、Claudeは公式の最新仕様を読んだうえで生成できます。公式のツール解説にある例は、天気APIをグラフに足す依頼です。

Add weather details to my schema using https://api.weather.gov so I can expose weather conditions for airport cities.

この依頼でClaudeがApollo Connectors Specを使い、REST APIと連携するグラフを生成するとされています。仕様の出力は大きく、画面には出ません。

CLAUDE.mdに入れる規約の断片

毎回の依頼で仕様の参照を指示するより、プロジェクトの CLAUDE.md に決めておく方が安定します。たとえば次のような断片です。

## Apollo Connectors
- Connectorsを追加・変更する前に、graphos MCPのApollo Connectors Specを必ず取得する
- 不明な指示子の挙動はApollo Docs Searchで調べ、Apollo Docs Readで該当ページを読んでから書く
- スキーマ先頭の @link でimportするconnectのバージョンは、現在のスキーマに合わせる
- 生成後は、プロジェクトのcompositionを確かめるコマンドを実行し、出力のエラーを読んで直す

最後の行が反復の核です。書いて終わりにせず、検証コマンドの出力をClaudeに読ませて直させます。検証の手段はプロジェクトによって違うので、規約には自分のコマンドを書いてください。

生成前にバージョンを揃える

Connectorsはスキーマが connect 仕様をimportして初めて動きます。公式の例は次の形です。

extend schema
  @link(
    url: "https://specs.apollo.dev/connect/v0.4"
    import: ["@connect", "@source"]
  )

仕様のバージョンごとに、必要な最小バージョンが決まっています。

Claudeが v0.4 で書いたスキーマを、Router 2.8のグラフに載せると合成できません。依頼文に、使っているRouterとビルドパイプラインのバージョンを添えると、この食い違いを防げます。

対象のREST APIが条件を満たすか

Connectorsは、JSONをHTTPで返すAPIと相性が良く、次のような条件が挙げられています。

• GET / POST / PUT / PATCH / DELETE を受け付ける
• 入力にパスセグメントとクエリ文字列を使う
• 成功時は200〜299のステータスを返す
• 返すプロパティの集合が決まっている(GraphQLには Map 型が無いため)
• 認証情報はリクエストヘッダーで受け取る
• 機微な情報をクエリパラメータに載せない(Routerがログとトレースに完全なURLを出すため)

最後の1点は、Claudeに書かせるときにも効きます。APIキーをクエリ文字列に埋め込むConnectorを出してきたら、ヘッダーに直させます。

書き込み系ツールの線引き

グラフ系のツールには、読むだけのものと、組織のデータを変えるものが混在します。ツール解説が実行前の確認を求めているのは、次のツールです。

読み取り側にもコストの罠があります。Get Graph Schemaは大きなフェデレーショングラフで80万文字を超え、約20万トークンになることがあり、多くのモデルのコンテキストウィンドウを超えます。フェデレーションでは、Get Subgraph Schemaでサブグラフを1つずつ読むよう案内されています。

メトリクス系にも時間の制約があります。集計と日次の結果は直近1日を含みません。時間単位は7日以内の窓で90日以内の開始、分単位は1日以内の窓で30日以内の開始が条件です。

Claude Codeの許可設定で止める

Claude Codeの許可ルールは、mcp__<server>__<tool> の形でツールを指定します。ドキュメント系の3つだけを自動承認し、残りは毎回確認する構成にできます。

{
  "permissions": {
    "allow": [
      "mcp__graphos__ApolloDocsSearch",
      "mcp__graphos__ApolloDocsRead",
      "mcp__graphos__ApolloConnectorsSpec"
    ]
  }
}

これらのツール名は、Apolloの設定例にある tools 配列の表記です。グラフ系の正確な名前は /mcp でツールを選ぶと表示されます。公開・削除・キー作成のツールは、その名前を deny か ask にフルネームで追加します。サーバー全体を許可すると書き込み系まで通るので、mcp__graphos__* のようなワイルドカードのallowは避けます。

読み取り専用のAPIキーという区分は、ツール解説にはありません。書き込みを持たせたくない用途では、グラフAPIキーで範囲を1つのグラフに絞り、上の許可ルールで二重に止めるのが現実的です。

どんな依頼から試すか

ドキュメント系だけなら、副作用はありません。まずここから始めるのが筋です。

• 既存のRESTサービスをスーパーグラフに束ねる @connect を書かせる
• Routerの設定項目を質問し、該当ページを読ませて答えさせる
• 書いたスキーマをLint Schemaにかけ、新しい違反だけを出させる(要認証)

サインイン後は、次のような依頼が公式に例示されています。

Is my graph <GRAPH_ID> healthy? Run the relevant checks and summarize findings as Attention Required, Review Recommended, or What's Working Well.

For <GRAPH_ID>, cross-reference the top operations with their latency/error metrics. Are any high-traffic operations that are also slow or failing?

読み取りの調査は、この種の横断質問でこそ効きます。複数のツールをClaudeが連鎖して呼び、結果を重大度で並べ直すからです。

GraphQLのAPIを別のMCPサーバー経由で叩く方法はGraphQL MCPサーバーでClaudeにAPIを叩かせるで、Claude CodeでGraphQLのコード生成を扱う設定はClaude CodeでGraphQL Codegenを使うで扱っています。

まとめ

GraphOS MCP Serverは、認証なしのドキュメント系から入り、必要になった段階でサインインに進める設計です。Connectorsを書かせる用途なら、Apollo Connectors Specを呼ばせ、Routerとビルドパイプラインのバージョンを依頼に添えるだけで精度が変わります。グラフ系に進むなら、公開・削除・キー作成のツールだけを許可ルールで止めてください。