# MCP server

Source: https://docs.graphops.xyz/subgraphs/mcp

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](./api).

## 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](/platform/api-keys#limit-a-key) 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](/ai-agents#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](./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](./concepts/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](./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](./guides/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`](/platform/errors/gateway#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](./guides/paginate-results).

## Results and errors

A tool error has `isError: true` and an `error` with a `code` from the
[error reference](/platform/errors), 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](./usage-and-limits#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](./usage-and-limits) for current rates.

## Next steps

* [Query data through MCP](/ai-agents#query-data-through-mcp): Add the Subgraphs MCP server to your coding agent.
* [Discover public Subgraphs](./guides/discover-public-subgraphs): Find a Subgraph ID or Deployment CID to query.
* [API integration](./api): Send the same queries from your application's code.