What can you do with this server?

The Subgraph Registry MCP server provides agent-friendly access to a pre-classified registry of 15,500+ subgraphs on The Graph Network, enabling intelligent subgraph discovery and selection. * Search & Filter Subgraphs: Query by domain (DeFi, NFTs, DAOs, gaming, etc.), network (Ethereum, Arbitrum, Base, etc.), protocol type (DEX, lending, bridge, etc.), canonical entity (liquidity_pool, trade, token, etc.), free-text keyword, or minimum reliability score. Results are ranked by reliability score and include ready-to-use query URLs. * AI-Powered Recommendations: Describe a natural-language goal (e.g., "find DEX trades on Arbitrum") to receive the best matching subgraphs with reliability scores and query URLs. * Full Subgraph Details: Retrieve comprehensive classification for a specific subgraph by ID or IPFS hash — domain, protocol type, canonical entities, entity field counts, reliability score with underlying signals (query fees, volume, curation, indexer stake), and query instructions. * Registry Statistics: Get an overview of the entire registry including total subgraph count and breakdowns by domain, network, and protocol type — useful for understanding available data before searching. * Reliability Scores: All results include a composite score (0–1) reflecting a subgraph's trustworthiness based on usage and community signals. * Flexible Integration: Supports stdio transport for local clients (Claude Desktop/Code) and SSE/HTTP for remote agents, with automated incremental registry updates.

Which integrations are available for this server?

Provides discovery and classification tools for subgraphs on the Ethereum network, allowing agents to search and filter protocol-specific data deployments. Analyzes and exposes metadata from GraphQL schemas of subgraphs, mapping entities to standard vocabularies and detecting schema forks or clones. Enables discovery and evaluation of subgraphs indexing the Optimism network, offering insights into protocol types, entity mappings, and usage signals. Facilitates discovery and metadata analysis for subgraphs deployed on the Polygon network, including domain classification and reliability scoring.

Subgraph Registry MCP

by PaulieB14

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Subgraph Registry

Agent-friendly semantic classification of all subgraphs on The Graph Network.

Pre-computed index of 15,330 subgraphs with domain classification, protocol type detection, schema fingerprinting, canonical entity mapping, and composite reliability scoring.

What's new in 0.8.0 — three agent-discovery upgrades:
Semantic search via 384-dim embeddings (semantic_search_subgraphs)
Schema evolution tracking with stability days surfaced on every result (get_schema_changes)
OpenAPI 3.1 spec auto-generated for MCP tools + REST routes, served at /.well-known/openapi.json

The Problem

Agents querying The Graph need to discover and select the right subgraph before they can query data. Today this requires 3-4 tool calls (search, check volumes, fetch schema, infer structure) before any real work happens. This registry flips that: agents start with structured knowledge, not a blank slate.

Related MCP server: The Graph Token API MCP

What It Does

Crawls all active subgraphs from the Graph Network meta-subgraph
Fetches the GraphQL schema for every deployment
Extracts contract addresses from each manifest's dataSources and templates — agents can answer "which subgraph indexes contract 0x… on chain X?"
Generates a per-subgraph starter GraphQL query from the parsed schema (real top entity, real fields, sensible orderBy) — no more generic boilerplate that doesn't compile against most subgraphs
Classifies each subgraph by domain, protocol type, canonical entities, and schema family
Scores reliability using on-chain signals (query fees, volume, curation, stake)
Returns x402 + legacy query URLs — agents can pay $0.01 USDC on Base per query (no API key) or use a Studio key
Publishes as SQLite database + REST API + MCP server + per-subgraph JSON-LD at /.well-known/subgraph/{id}.jsonld for ecosystem crawlers
Generates visual dashboards and bot-readable category files (auto-updated with each sync)

Querying with x402 (no API key)

Every result includes query_url_x402 alongside the legacy query_url. The Graph's public x402 gateway (live since 2026-05-08) accepts $0.01 USDC on Base per query with zero signup.

// An x402-native agent — discovery to data in two calls
const { recommendations } = await mcp.call("recommend_subgraph", {
  goal: "find DEX trades on Arbitrum",
});
const top = recommendations[0];

// POST your GraphQL query. The first call returns HTTP 402 with a
// base64 `payment-required` header; the x402 client signs the
// EIP-3009 USDC transfer on Base and retries automatically.
const data = await x402Fetch(top.query_url_x402, {
  method: "POST",
  body: JSON.stringify({ query: "{ swaps(first: 5) { id amountUSD } }" }),
});

Pricing manifest returned per subgraph:

{
  "amount_usd": 0.01,
  "asset": "USDC",
  "asset_contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chain": "base",
  "network": "eip155:8453",
  "pay_to": "0x79DC34E41B2b591078d3dE222C43EcaaBD52FcCB",
  "scheme": "exact",
  "asset_transfer_method": "eip3009"
}

Client libraries: @graphprotocol/client-x402, x402-fetch, or any generic x402 wrapper.

Registry at a Glance

Charts auto-generated from registry.db on each sync. See python/generate_docs.py.

Browse by Category

Domains

Explore subgraphs by use case — each file lists the top 25 subgraphs ranked by reliability score.

Domain	Count	File
DeFi	7,844	Swaps, pools, lending, vaults, yield
NFTs	1,565	Collections, marketplaces, sales
Unclassified	1,333	Not confidently classified
Infrastructure	1,251	Indexers, oracles, registries
Identity	1,061	ENS, name services, resolvers
Analytics	766	Snapshots, metrics, historical data
DAO	758	Governance, proposals, voting
Gaming	585	Players, quests, items, worlds
Social	167	Profiles, posts, follows

Full index: docs/DOMAINS.md

Networks

Explore subgraphs by blockchain — each file lists the top 25 subgraphs on that chain.

Network	Count	File
Ethereum	2,484	Largest ecosystem
Base	1,841	Fast-growing L2
BSC	1,670	BNB Chain
Arbitrum	1,437	Leading L2
Polygon	1,304	Polygon PoS
Optimism	580	OP Stack L2
Avalanche	453	C-Chain

Full index: docs/NETWORKS.md

Protocol Types

Type	Count	Description
DEX	4,411	Uniswap, Sushi, Curve, Balancer, PancakeSwap
Lending	1,469	Aave, Compound, Morpho, Spark, Silo
Staking	898	Lido, Rocket Pool, EigenLayer, Graph Network
Bridge	836	Hop, Stargate, Across, Wormhole, LayerZero
NFT Marketplace	450	OpenSea, Blur, Rarible, Foundation
Yield Aggregator	425	Yearn, Beefy, Harvest, Convex
Governance	425	Snapshot, Tally, Compound Governor
Perpetuals	273	GMX, Gains, dYdX, Hyperliquid
Name Service	227	ENS, Space ID, Unstoppable Domains
Options	192	Premia, Dopex, Lyra, Hegic

Reliability Score

Each subgraph gets a composite reliability score (0-1) based on four on-chain signals:

Signal	Weight	What it measures
Query Fees	30%	GRT fees earned from actual usage
Query Volume	30%	30-day query count
Curation Signal	20%	GRT tokens curated by the community
Indexer Allocation	20%	GRT allocated to this subgraph by indexers

All values are log-scaled and capped at 1.0. A 0.5 penalty is applied if the subgraph has been denied/deprecated.

Score tiers: High (0.7+) = strong signal, real usage | Medium (0.3-0.7) = functional, some activity | Low (<0.3) = minimal signal or test deployment

The score measures traction, so it measures age

All four inputs are cumulative — fees and curation accrue, volume needs 30 days to exist at all. A subgraph deployed last month therefore scores near zero no matter how good it is. Measured on the current corpus (served, non-denied):

Age	Count	Avg reliability
< 30 days	64	0.107
30–90 days	227	0.143
90–365 days	1,100	0.225
> 1 year	4,034	0.313

The newest subgraph anywhere in the registry's top 25 is 280 days old — yet 59 of those 64 sub-30-day subgraphs are already serving real query volume.

Rather than reweight the score and trade a measurable signal for a guess, search_subgraphs returns young matches in a separate emerging list alongside an emerging_caveat explaining that a low score at that age is expected rather than damning. Every result also carries age_days and maturity (new < 30d, emerging < 90d, established). This matters most for new chains and new protocols, where no mature deployment can exist — searching "perpetual futures" surfaces years-old Ethereum and BSC deployments in the main list and the 40-day-old Monad perps subgraph under emerging.

semantic_search_subgraphs ranks by cosine similarity rather than reliability, so it is already age-neutral — it carries the maturity labels but no emerging list, because a three-week-old subgraph can top it on merit.

Ranking

Three tools rank, and each ranks differently on purpose:

search_subgraphs — orders by how many of your query terms matched, then by reliability. OR-ing the terms and ordering on reliability alone meant a popular subgraph matching one incidental word beat a precise match on all three, so being more specific returned worse answers. Version tokens (v2, v3, v4) are kept rather than dropped as too short.
semantic_search_subgraphs — orders by semantic_score × (0.5 + 0.5 × reliability). Pure cosine put testnets first, since their text is nearly identical to mainnet's. The 0.5 floor keeps new subgraphs competitive.
recommend_subgraph — infers domain and protocol type from the goal, but as a ranking bonus, never a filter. As a filter, one bad keyword collapsed the candidate pool to nothing.

A term matching a subgraph's name counts for more than one matching its description — %ens% also matches "tokens", so equal weighting handed a search for ens to four Uniswap subgraphs.

Chain names are aliased, so ethereum, arbitrum, polygon and bnb resolve to the corpus values mainnet, arbitrum-one, matic and bsc.

Testnets

723 of the 5,425 served subgraphs are on testnets, and their text is nearly identical to their mainnet twins', so they compete for the top slot. They are excluded by default and every result carries testnet: true|false. Pass include_testnets: true to see them — and an explicit request for a testnet network (network: "sepolia") always wins over the default, so that still returns exactly what you asked for.

Using the registry from payql

payql can use this registry as its free discovery source instead of paying for a network-subgraph query. Run the registry's HTTP transport and point payql at it:

npx subgraph-registry-mcp --http-only          # serves :3848
PAYQL_REGISTRY_URL=http://127.0.0.1:3848/graphql npx -y payql

POST /graphql answers in the Graph network subgraph's subgraphMetadataSearch shape, which is what payql already parses — so this needs no change on payql's side, and discovery becomes free and locally-ranked.

Denied deployments

Curation-denied deployments (deniedAt > 0 — denied indexing rewards, usually spam, duplicates or deprecations) are excluded by default from search_subgraphs, semantic_search_subgraphs and recommend_subgraph. Pass include_denied: true to the two search tools to see them; every result then carries denied: true|false so the choice stays visible.

MCP Server

The registry is available as an MCP server with dual transport — stdio for local clients and SSE/HTTP for remote agents.

Same abilities as graphops/subgraph-mcp (hosted SSE https://subgraphs.mcp.thegraph.com/sse), better discovery. Schema, execute, contract-lookup and 30-day counts use the official tool names so an agent can swap connectors. Search stays on our names (search_subgraphs, recommend_subgraph, semantic_search_subgraphs) because they already beat official search_subgraphs_by_keyword (reliability, real query_volume_30d, network).

Official workflow says ALWAYS call get_deployment_30day_query_counts before selecting. Skip that extra round-trip here — every search/recommend hit already carries query_volume_30d. The counts tool still exists under the official name and reads those same registry figures. Official counts have been observed returning 0 for ENS, Lido and Uniswap; we do not copy those zeros.

The shipped server is the Node implementation in src/index.js; that's what npx subgraph-registry-mcp runs and what's published to npm. A Python equivalent in python/mcp_server.py is kept for local development against the same SQLite database — bug fixes and new tools should land in the Node version first.

Discovery tools (never execute GraphQL, never introspect live schemas):

search_subgraphs — filter by domain, network, protocol type, entity, or keyword. Ranked by matched terms, reliability and real query_volume_30d.
recommend_subgraph — natural language goal to best subgraphs (includes schema_stable_days)
semantic_search_subgraphs — vector-similarity search over precomputed embeddings (sentence-transformers/all-MiniLM-L6-v2, 384-dim). Use for fuzzy/paraphrased goals where literal keyword match would miss.
get_subgraph_detail — full classification for a specific subgraph (includes schema_changed_at and crawled contract_addresses)
list_registry_stats — registry overview (domains, networks, counts)
get_schema_changes — chronological schema-fingerprint history for a subgraph (one row per detected change). Helps agents prefer mature subgraphs whose data contract has been stable.

Opt-in query / schema (caller must invoke; search never auto-queries). Official names for connector swap-in:

execute_query_by_subgraph_id / execute_query_by_deployment_id / execute_query_by_ipfs_hash — POST GraphQL to The Graph gateway. Same routing as official (subgraphs/id vs deployments/id). Requires THE_GRAPH_STUDIO_API_KEY (or GATEWAY_API_KEY). Without a key, returns {error: credentials_required, query_url, query_url_x402, hint} immediately — no hang, no x402 auto-pay. Convenience superset: execute_query accepts id OR deployment_id OR ipfs_hash.
get_schema_by_subgraph_id / get_schema_by_deployment_id / get_schema_by_ipfs_hash — local registry_schema (entities, example_query, fingerprint) with no network when the subgraph is in the corpus; live __schema introspection only when a Studio key is set. Convenience superset: get_schema.
get_top_subgraph_deployments(contract_address, chain) — official name. Official chain is graph-node ids (mainnet, not ethereum); we accept both. Top 3 from crawled manifests, ranked by reliability then real 30-day volume (not official query-fees / 0-count oracle). Substreams-powered subgraphs often have no dataSources addresses — that gap is reported, not faked.
get_deployment_30day_query_counts — official name, ipfs_hashes in. Real registry query_volume_30d. Unknown hashes return not_in_registry rather than a fake 0. Usually unnecessary: the same number is already on every search hit.

Set THE_GRAPH_STUDIO_API_KEY in the MCP host env to enable execute/live-schema. No private key is bundled. The keyed gateway often returns HTTP 200 with a GraphQL error body when auth is missing — execute_query surfaces http_status and errors honestly.

Install

# Claude Code
claude mcp add subgraph-registry -- npx subgraph-registry-mcp

# Claude Desktop
{
  "mcpServers": {
    "subgraph-registry": {
      "command": "npx",
      "args": ["subgraph-registry-mcp"],
      "env": {
        "THE_GRAPH_STUDIO_API_KEY": "your-studio-key"
      }
    }
  }
}

# Remote agents (SSE)
npx subgraph-registry-mcp --http-only
# Then connect to http://localhost:3848/sse

The server auto-downloads the pre-built registry (8MB SQLite) from GitHub on first run.

Well-Known JSON-LD Manifest

Stable, machine-readable per-subgraph manifest that other crawlers and agent frameworks can index without going through MCP. Served by the Node MCP HTTP transport:

GET /.well-known/subgraph/{id}.jsonld     Full per-subgraph manifest (JSON-LD)
GET /subgraphs/{id}.jsonld                 Alias (same payload)
GET /.well-known/subgraph-index.jsonld     Discovery list — top 100 by reliability with @id links

Each manifest includes classification, parsed entities, contract addresses (from the indexed dataSources), endpoints (x402 + API-key), a per-subgraph starter query generated from the actual schema, pricing, and metadata. The @context + @type make the shape auto-discoverable.

# Start the HTTP transport
npx subgraph-registry-mcp --http-only

# Fetch the manifest for Uniswap V3 Mainnet
curl http://localhost:3848/.well-known/subgraph/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV.jsonld

Semantic Search

Every subgraph has a precomputed 384-dim embedding from sentence-transformers/all-MiniLM-L6-v2, built from its display name, description, canonical entities, top schema entity names, and protocol metadata. At MCP-tool-call time the Node server embeds the query string with the same model (via @xenova/transformers, quantized ONNX bundled in the npm package — no first-call download) and ranks rows by cosine similarity.

const { subgraphs } = await mcp.call("semantic_search_subgraphs", {
  query: "lending positions near liquidation on a Layer 2",
  limit: 5,
});
// subgraphs[i].semantic_score is cosine similarity in [0, 1]; >0.5 ~= strong match.

Use it when:

The goal is paraphrased or use-case-shaped (search_subgraphs is keyword-only).
You're exploring "what data exists for X?" rather than fetching a specific protocol's subgraph.

Same model is shared between Python crawl-time (fastembed) and JS runtime (@xenova/transformers) — vectors are bitwise-comparable so cosine math gives consistent rankings across runtimes.

Embeddings add ~22 MB to registry.db (14k × 384 × 4 bytes); model bundle adds ~23 MB to the npm package.

Schema Evolution

Each crawl computes a schema_fingerprint (MD5 of sorted entity:field_count pairs) per subgraph. Whenever the fingerprint changes from the previous sync, an immutable row is written to schema_history. The table is append-only and survives full DB rebuilds.

const history = await mcp.call("get_schema_changes", {
  subgraph_id: "5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV",
});
// {
//   total_changes: 3,
//   stable_days: 47.2,
//   changed_within_24h: false,
//   changed_within_7d: false,
//   changes: [
//     { fingerprint: "abc123...", prev_fingerprint: "def456...", detected_at: 1717... },
//     ...
//   ]
// }

recommend_subgraph and get_subgraph_detail results now also include schema_changed_at (unix seconds of last detected change) and schema_stable_days so agents can prefer subgraphs whose data contract has been stable longer — useful when a query needs to keep working across the agent's planning horizon.

OpenAPI

The full API surface (MCP tools + REST routes) is published as OpenAPI 3.1:

openapi.yaml — checked into the repo, single source of truth
data/openapi.json — bundled with the npm tarball
GET /.well-known/openapi.json — served by the HTTP transport for live discovery

The spec is regenerated on every release from the declarative TOOLS[] + REST_ROUTES[] exports in src/index.js via scripts/gen-openapi.js. CI fails any PR that touches src/index.js without regenerating the spec.

REST API

GET /summary                    Registry overview and stats
GET /domains                    Domain breakdown
GET /networks                   Network breakdown
GET /families                   Schema family groups (fork/clone detection)
GET /subgraphs                  Filter subgraphs
GET /subgraphs/{id}             Full detail for one subgraph (now includes contract_addresses and example_query)
GET /search?q=uniswap           Free-text search
GET /recommend?goal=...&chain=  Agent-optimized recommendation

# Start API server
cd python && python server.py

# Example: find DEX subgraphs on Arbitrum
curl "http://localhost:3847/recommend?goal=query+DEX+trades+on+Arbitrum&chain=arbitrum-one"

# Example: filter by entity type
curl "http://localhost:3847/subgraphs?entity=liquidity_pool&network=base&min_reliability=0.5"

Bot-Readable Category Files

The docs/ directory contains structured .md files with YAML frontmatter designed for AI agents and bots to consume:

docs/
├── DOMAINS.md           # Index of all domains with counts
├── NETWORKS.md          # Index of all networks with counts
├── charts/              # Auto-generated SVG visualizations
│   ├── domains.svg
│   ├── networks.svg
│   ├── protocol-types.svg
│   └── reliability.svg
├── domains/             # One file per domain
│   ├── defi.md          # Top 25 DeFi subgraphs by reliability
│   ├── nfts.md
│   ├── dao.md
│   └── ...
└── networks/            # One file per network
    ├── mainnet.md       # Top 25 Ethereum subgraphs by reliability
    ├── base.md
    ├── arbitrum-one.md
    └── ...

Each category file includes:

YAML frontmatter (domain/network, count, percentage, last updated)
Top 25 subgraphs ranked by reliability score
MCP tool and REST API query examples

Architecture

Graph Network Subgraph (meta-subgraph, 140M queries/month)
    |
    v
crawler.py ---- async httpx, ID-based cursor pagination
    |
    v
classifier.py - rule-based domain/protocol classification + schema fingerprinting
    |
    v
registry.py --- builds SQLite + indices
    |
    ├── server.py ------ FastAPI REST API (:3847)
    ├── generate_docs.py SVG charts + category .md files
    └── scheduler.py --- weekly incremental sync

MCP Server (src/index.js, published to npm)
    ├── stdio   ←── Claude Desktop / Claude Code
    └── SSE     ←── OpenClaw / remote agents (:3848)

python/mcp_server.py — local-dev MCP server hitting the same SQLite DB

Quick Start (Local Build)

cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

echo "GATEWAY_API_KEY=your-key-here" > .env

# Full crawl + classify (~11 min)
python registry.py

# Generate charts and category files
python generate_docs.py

# Start API server
python server.py

How It Stays Current

A GitHub Actions workflow runs every 3 days:

Incremental crawl (updatedAt_gte: lastSyncTimestamp)
Reclassify new/changed subgraphs
Regenerate SVG charts and category .md files
Commit and push updates

License

MIT

Available Tools

4 tools

get_subgraph_detailA

Get full classification detail for a specific subgraph by its subgraph ID or IPFS hash. Returns domain, protocol type, canonical entities, all entity names with field counts, reliability score, signal data, query URL, and step-by-step query instructions.

ParametersJSON Schema

Name	Required	Description	Default
`subgraph_id`	Yes	Subgraph ID or IPFS hash (Qm...)

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the return format (listing specific data points like domain, protocol type, entities, reliability score, etc.), which is crucial for understanding output. However, it lacks details on error handling, rate limits, or authentication needs, leaving some behavioral aspects unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in two sentences: the first states the purpose and parameter, and the second details the return values. Every element contributes directly to understanding the tool's function and output, with no redundant or unnecessary information, making it highly concise and well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description provides a complete overview of purpose and detailed return values, which compensates for the lack of output schema. However, it could improve by addressing potential errors or usage constraints, slightly limiting completeness for safe operation by an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the single parameter 'subgraph_id' clearly documented in the schema. The description adds minimal value by restating that it accepts 'subgraph ID or IPFS hash', which is already covered in the schema's description. No additional syntax, format, or contextual details beyond the schema are provided, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get full classification detail'), target resource ('specific subgraph'), and identification method ('by its subgraph ID or IPFS hash'). It distinguishes from sibling tools like list_registry_stats (aggregate statistics), recommend_subgraph (recommendations), and search_subgraphs (searching multiple subgraphs) by focusing on detailed retrieval for a single identified subgraph.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when detailed classification information for a specific subgraph is needed, but does not explicitly state when to use this tool versus alternatives like search_subgraphs (which might return less detail) or recommend_subgraph (which suggests subgraphs). No explicit exclusions or prerequisites are provided, leaving some ambiguity about optimal use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_registry_statsA

Get an overview of the subgraph registry: total count, available domains, networks, and protocol types with counts. Use this to understand what data is available before searching.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes what the tool returns (overview with counts) but doesn't disclose behavioral traits like whether it's read-only, if it requires authentication, rate limits, or error conditions. The description is accurate but lacks operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with two sentences that each earn their place. The first sentence states the purpose and return values, the second provides usage guidance. No wasted words, well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description provides adequate context about what the tool does and when to use it. However, without annotations or output schema, it lacks details about return format, error handling, or operational constraints that would be helpful for a registry overview tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage. The description appropriately doesn't discuss parameters since none exist. It focuses on the tool's purpose and usage context, which is correct for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get an overview of the subgraph registry' with specific details about what it returns (total count, available domains, networks, and protocol types with counts). It distinguishes from siblings by mentioning this is for understanding available data before searching, but doesn't explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: 'to understand what data is available before searching.' This implies it should be used as an initial overview before using search tools like 'search_subgraphs.' However, it doesn't explicitly state when NOT to use it or name specific alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recommend_subgraphA

Given a natural-language goal like 'find DEX trades on Arbitrum' or 'get lending liquidation data', returns the best matching subgraphs with reliability scores and query URLs. Automatically infers domain and protocol type from the goal. Each result includes a query_url — replace [api-key] with your Graph API key to query live data.

ParametersJSON Schema

Name	Required	Description	Default
`goal`	Yes	What you want to do, e.g. 'query Uniswap pool data on Base'
`chain`	No	Optional chain filter: mainnet, arbitrum-one, base, matic, etc.

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behaviors: automatic inference of domain/protocol type, inclusion of reliability scores and query URLs, and the need to replace [api-key] for live queries. However, it lacks details on error handling, rate limits, or authentication requirements, leaving gaps for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with every sentence earning its place. It efficiently explains the tool's function, input processing, output components, and usage instruction without redundancy or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description provides a solid foundation but has gaps. It covers the tool's purpose, input interpretation, and output structure, but lacks details on error cases, performance characteristics, or exact return format. For a recommendation tool with 2 parameters and no structured output documentation, this is adequate but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters (goal and chain). The description adds marginal value by emphasizing the natural-language aspect of 'goal' and mentioning optional chain filtering, but does not provide additional syntax or format details beyond what the schema specifies. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('returns the best matching subgraphs') and resources ('subgraphs with reliability scores and query URLs'). It distinguishes from siblings by focusing on recommendation based on natural-language goals rather than detailed lookup (get_subgraph_detail), statistical listing (list_registry_stats), or general search (search_subgraphs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('Given a natural-language goal...'), but does not explicitly state when not to use it or name specific alternatives among the sibling tools. It implies usage for goal-based matching rather than direct queries or searches, offering good guidance without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_subgraphsA

Search and filter the classified subgraph registry (15,500+ subgraphs). Filter by domain (defi, nfts, dao, gaming, identity, infrastructure, social, analytics), network (mainnet, arbitrum-one, base, matic, bsc, optimism, avalanche), protocol_type (dex, lending, bridge, staking, options, perpetuals, nft-marketplace, yield-aggregator, governance, name-service), canonical entity type (liquidity_pool, trade, token, position, vault, loan, collateral, liquidation, nft_collection, nft_item, nft_sale, proposal, delegate, domain_name, account, transaction, daily_snapshot, hourly_snapshot), or free-text keyword. Returns subgraphs ranked by reliability score with query URLs. To query data: POST GraphQL to https://gateway.thegraph.com/api/[api-key]/subgraphs/id/[subgraph-id] (get API key from https://thegraph.com/studio/apikeys/).

ParametersJSON Schema

Name	Required	Description
`query`	No	Free-text search across names and descriptions
`domain`	No	Filter by domain: defi, nfts, dao, gaming, identity, infrastructure, social, analytics
`network`	No	Filter by chain: mainnet, arbitrum-one, base, matic, bsc, optimism, avalanche, etc.
`protocol_type`	No	Filter by protocol type: dex, lending, bridge, staking, options, perpetuals, etc.
`entity`	No	Filter by canonical entity: liquidity_pool, trade, token, position, vault, loan, etc.
`min_reliability`	No	Minimum reliability score (0-1). Higher = more signal/stake/fees.
`limit`	No	Max results to return (default: 20)

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well: it discloses the registry size (15,500+ subgraphs), ranking method (by reliability score), return format (query URLs), and post-search workflow (how to actually query data with API key). It doesn't mention rate limits, authentication needs, or pagination behavior, but provides substantial operational context beyond basic functionality.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence establishes core functionality, followed by filter options, return format, and post-usage instructions. Every sentence adds value, though the long list of example values in the first sentence could be slightly streamlined.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters with full schema coverage but no annotations or output schema, the description provides good context: it explains what the tool does, how results are ranked, what's returned (query URLs), and crucial next steps for data querying. The main gap is lack of output format details, but the description compensates well with operational guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal value beyond the schema by listing example values for filters (e.g., 'defi, nfts, dao' for domain) and clarifying that 'query' is 'free-text keyword' search. This meets the baseline 3 when schema does heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search and filter the classified subgraph registry (15,500+ subgraphs)' with specific verbs ('search', 'filter') and resource ('subgraph registry'). It distinguishes from siblings by focusing on search/filtering capabilities rather than detail retrieval (get_subgraph_detail), statistics (list_registry_stats), or recommendations (recommend_subgraph).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool vs alternatives: 'To query data: POST GraphQL to https://gateway.thegraph.com/api/[api-key]/subgraphs/id/[subgraph-id]' indicates this tool is for discovery/filtering, while actual data querying requires a different API call. It also implicitly contrasts with siblings by focusing on search/filtering rather than other operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv1.0.0Mar 12, 2026
- First observedget_subgraph_detail
- First observedlist_registry_stats
- First observedrecommend_subgraph
- First observedsearch_subgraphs

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored 2026-04-13 22:35 across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: get_subgraph_detail retrieves detailed metadata for a specific subgraph, list_registry_stats provides high-level registry overview, recommend_subgraph offers goal-based recommendations, and search_subgraphs enables filtered discovery. There is no overlap in functionality, making tool selection straightforward for an agent.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (get_subgraph_detail, list_registry_stats, recommend_subgraph, search_subgraphs) with clear, descriptive verbs that align with their actions. The naming is uniform and predictable across the set.

Tool Count5/5

With 4 tools, the server is well-scoped for its purpose of subgraph registry interaction. The tools cover key workflows: exploration (list_registry_stats), discovery (search_subgraphs, recommend_subgraph), and detailed access (get_subgraph_detail), without being overly sparse or bloated.

Completeness4/5

The toolset provides comprehensive coverage for querying and discovering subgraphs, including overview, search, recommendation, and detail retrieval. A minor gap is the lack of tools for managing or updating registry entries (e.g., add/remove subgraphs), but this is reasonable for a read-only registry interface focused on data access.

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Realmint A
io.github.realmint-io
Agent-native scoring, search and routing for tokenized real-world assets across multi-chain.
Blockchain Finance
162
PreFlyte — DeFi Financial Intelligence for AI Agents A
xyz.preflyte
Evidence-based market data for AI agents deploying capital in DeFi. Empirical, not advertised.
Finance Blockchain Web3 & Decentralized Tech
92
DELPHI Oracle
io.github.achilliesbot
Real-time AI intelligence signals and temporal knowledge graph for agent economy
Knowledge & Memory AI & Machine Learning Autonomous Agents
21
WhisperGraphOAuth
io.github.whisper-sec
The internet's infrastructure graph for AI agents - 46B nodes and edges, free trial via 2 HTTP calls
Networking & Infrastructure Security
21

Related MCP Servers

TheGraph MCP Server
Blockchain Web3 & Decentralized Tech RAG Systems
kukapay
A
license
A
quality
F
maintenance
Powers AI agents with indexed blockchain data from The Graph, enabling them to fetch subgraph schemas and execute GraphQL queries against blockchain data.
Updated a year ago (2025-07-31 09:46 UTC)
2
9
MIT
The Graph Token API MCP
pinax-network
A
license
Not graded
quality
F
maintenance
Official MCP server that turns The Graph’s Token API into a plug-and-play web3 data tool. Exposes ERC-20 & NFT metadata, balances, transfers, top-holder stats, prices, and more, allowing LLMs to run SQL queries on structured and indexed blockchain data.
Updated a year ago (2025-07-23 21:44 UTC)
2
Apache 2.0
GraphQL Schema Embedder MCP
Databases RAG Systems Search
ThoreKoritzius
A
license
Not graded
quality
D
maintenance
Indexes GraphQL schemas using embeddings to enable semantic search of types and fields for fast lookup. It allows LLMs to discover relevant schema signatures and execute queries against live GraphQL endpoints.
Updated 5 months ago (2026-04-03 07:41 UTC)
MIT
thegraph-mcp
Blockchain Web3 & Decentralized Tech Search
Data-Nexus-Web3
A
license
A
quality
D
maintenance
An MCP server that powers AI agents with indexed blockchain data from The Graph.
Updated 7 months ago (2026-02-21 06:37 UTC)
3
MIT