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
| Setting | Value |
|---|---|
| URL | https://subgraphs.graphops.xyz/v1/mcp |
| Transport | Streamable HTTP, JSON responses only |
| Protocol versions | 2026-07-28, 2025-11-25 and 2025-06-18 |
| Authentication | Authorization: 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.
| Tool | Use |
|---|---|
subgraph_get_schema | Read the Subgraph's GraphQL schema before writing a query. |
subgraph_get_meta | Read the block the Subgraph has indexed up to, and whether it has indexing errors. |
subgraph_query | Run one GraphQL query and get the block the data reflects. |
Name the Subgraph
Every tool takes target, which holds exactly one identifier:
| Field | Identifier | Serves |
|---|---|---|
deploymentId | A Deployment CID, such as Qm… or bafy… | That deployment. |
subgraphId | A Graph Network Graph Network Subgraph ID | The version its owner selected on The Graph Network. |
alias | One of your organization's Endpoint Aliases | The 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.
indexedHeadis the block the data reflects. To read a fixed block, pass the sameblock: { number: N }to every root field;indexedHeadis then that block. - Page size. A list field returns
firstitems, 100 by default. graph-node capsfirstandskip. - Next page. For each root list field that returned a full page in ascending
idorder,pagesgives the arguments for the next page:where: { id_gt: <last id> },orderBy: idandskip: 0. Keep the field's other filters andfirst. 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:
action | Meaning | Examples |
|---|---|---|
fix_arguments | Change the arguments, then call again. | tool_arguments_invalid, deployment_not_found, subgraph_identifier_invalid |
narrow_request | Ask for less data. | upstream_response_too_large |
retry_later | Retry the same call after a wait. | upstream_timeout, subgraph_resolution_unavailable |
stop | Stop 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
| Limit | Value |
|---|---|
| Tool result | 96 KiB (98,304 bytes); a larger result fails with upstream_response_too_large |
| Request body | 512 KiB |
| Time per tool call | 30 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