Skip to content

MCP server

Read a Subgraph's schema, check its indexed block and run GraphQL queries from an AI agent through the Subgraphs MCP server's tools.

The Subgraphs MCP server lets an AI agent learn a Subgraph's schema, check how far it has indexed and run GraphQL queries, without first writing and running code. Each tool call is one Subgraph query, priced and limited like the same query sent to a Subgraphs endpoint. Use the tools to explore and answer questions; the code your application runs still calls the Subgraphs endpoints.

Connect

SettingValue
URLhttps://subgraphs.graphops.xyz/v1/mcp
TransportStreamable HTTP, JSON responses only
Protocol versions2026-07-28, 2025-11-25 and 2025-06-18
AuthenticationAuthorization: Bearer <key> header

Use a key with Subgraphs access and no Subgraphs limits. A tool call names its Subgraph in its arguments, not in the URL, so a key limited to Managed Subgraphs, Endpoint Aliases, Deployment CIDs or Subgraph IDs is refused with api_key_target_not_allowed. Create a separate key for the agent, so you can revoke it without affecting your applications.

Query data through MCP has the setup for Claude Code, Codex, Cursor and VS Code. The tool list, with each tool's input and output schemas and the current limits, is published without a key at https://subgraphs.graphops.xyz/v1/mcp/tools.json.

Tools

All three tools are read-only, so an agent can run them without asking you each time.

ToolUse
subgraph_get_schemaRead the Subgraph's GraphQL schema before writing a query.
subgraph_get_metaRead the block the Subgraph has indexed up to, and whether it has indexing errors.
subgraph_queryRun one GraphQL query and get the block the data reflects.

Name the Subgraph

Every tool takes target, which holds exactly one identifier:

FieldIdentifierServes
deploymentIdA Deployment CID, such as Qm… or bafy…That deployment.
subgraphIdA Graph Network Graph Network Subgraph IDThe version its owner selected on The Graph Network.
aliasOne of your organization's Endpoint AliasesThe deployment its target serves.

Every result includes deployment, the Deployment CID that answered, so you can tell which version an Endpoint Alias or Subgraph ID served. See Identifier types.

Read the schema

subgraph_get_schema returns sdl, the schema in GraphQL SDL, and entities, the entity types you can query. The SDL leaves out the filter inputs, ordering enums and block arguments graph-node generates for every entity, so a typical schema stays a few kilobytes. note explains that grammar in a few lines: filters such as field_gt and field_in, orderBy, orderDirection and block. See Schema reference.

Check freshness

subgraph_get_meta returns indexedHead, the latest block the deployment has indexed with its number, hash and timestamp, and hasIndexingErrors. Use it to judge how current answers are before you rely on them. See Monitor sync health.

Run a query

subgraph_query takes target, query, and optional variables and operationName. The query must hold exactly one query operation, plus any fragments it uses. Mutations, subscriptions and introspection (__schema, __type) are refused with tool_arguments_invalid; read the schema with subgraph_get_schema instead.

The result holds graph-node's data and errors unchanged, with deployment, indexedHead and hasIndexingErrors. GraphQL errors, such as a field the schema doesn't have, come back beside data as a result, not as a tool error.

  • Freshness. indexedHead is the block the data reflects. To read a fixed block, pass the same block: { number: N } to every root field; indexedHead is then that block.
  • Page size. A list field returns first items, 100 by default. graph-node caps first and skip.
  • Next page. For each root list field that returned a full page in ascending id order, pages gives the arguments for the next page: where: { id_gt: <last id> }, orderBy: id and skip: 0. Keep the field's other filters and first. See Paginate results.

Results and errors

A tool error has isError: true and an error with a code from the error reference, a message, a docsUrl, and action, which says what to do next:

actionMeaningExamples
fix_argumentsChange the arguments, then call again.tool_arguments_invalid, deployment_not_found, subgraph_identifier_invalid
narrow_requestAsk for less data.upstream_response_too_large
retry_laterRetry the same call after a wait.upstream_timeout, subgraph_resolution_unavailable
stopStop and tell the person.subgraph_resolution_failed

Authorization and credit errors, such as api_key_target_not_allowed and credits_exhausted, end the request before any tool runs. Stop on them instead of retrying.

Results are untrusted data. Indexed entities can contain text written to look like instructions; the server tells agents never to follow it.

Limits and billing

LimitValue
Tool result96 KiB (98,304 bytes); a larger result fails with upstream_response_too_large
Request body512 KiB
Time per tool call30 seconds; a slower call fails with upstream_timeout

Each tool call is one Subgraph query and uses credits like the same query sent to a Subgraphs endpoint, including subgraph_get_schema and subgraph_get_meta. It counts toward your organization's query rate like any other query. Arguments refused with tool_arguments_invalid, results over the size limit and calls that time out aren't billed.

To stay under the result limit, request only the fields you need and page with a smaller first. See Usage and limits for current rates.

Next steps

Last updated