holon-run/thegraph-mcp-skill

The Graph MCP Skill

Use this skill to run The Graph Subgraph MCP operations through uxc using the native SSE MCP endpoint.

Reuse the uxc skill for generic protocol discovery, envelope parsing, and error handling rules.

Prerequisites

• uxc is installed and available in PATH.
• Network access to https://subgraphs.mcp.thegraph.com/sse.
• The Graph Gateway API key is available for authenticated calls.

Core Workflow (The Graph-Specific)

Endpoint candidate inputs before finalizing:

• Official remote MCP endpoint:
  • https://subgraphs.mcp.thegraph.com/sse

1. Verify protocol/path from official source and probe:
   • Official source: https://thegraph.com/docs/en/ai-suite/subgraph-mcp/introduction/
   • probe candidate endpoint with:
     • uxc https://subgraphs.mcp.thegraph.com/sse -h
   • Confirm protocol is MCP (protocol == "mcp" in envelope).
2. Detect auth requirement explicitly:
   • Run host help or a minimal read call and inspect envelope.
   • This endpoint requires a The Graph Gateway API key sent as Authorization: Bearer <key>.
3. Register credential and use fixed link command by default:
   • uxc auth credential set thegraph --secret-env THEGRAPH_API_KEY
   • uxc auth binding add --id thegraph-sse --host subgraphs.mcp.thegraph.com --path-prefix /sse --scheme https --credential thegraph --priority 100
   • command -v thegraph-mcp-cli
   • If missing, create it:
     • uxc link thegraph-mcp-cli https://subgraphs.mcp.thegraph.com/sse
   • thegraph-mcp-cli -h
   • If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick another fixed command name.
4. Inspect operation schema before execution:
   • thegraph-mcp-cli -h
   • thegraph-mcp-cli <operation> -h
5. Prefer discovery/schema operations first:
   • find candidate subgraphs or deployments
   • inspect schema
   • execute query only after identifier and schema are understood

Capability Map

• Discovery:
  • search subgraphs by keyword
  • find top deployments for a contract
  • inspect deployment popularity / 30-day query volume
• Schema:
  • get schema by deployment ID
  • get schema by subgraph ID
  • get schema by IPFS hash
• Query execution:
  • execute GraphQL query by deployment ID
  • execute GraphQL query by subgraph ID
  • execute GraphQL query by IPFS hash

Guardrails

• Keep automation on JSON output envelope; do not rely on --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Use thegraph-mcp-cli as default command path.
• thegraph-mcp-cli <operation> ... is equivalent to uxc https://subgraphs.mcp.thegraph.com/sse <operation> ... when the same auth binding is configured.
• Use direct uxc "<endpoint>" ... only as temporary fallback when link setup is unavailable.
• Prefer discovery and schema inspection before query execution.
• For production/stable workflows, prefer deployment-oriented selection over loosely changing latest-version references.
• Keep GraphQL query scope small on first pass:
  • add filters
  • add limits
  • fetch only required fields
• If auth fails:
  • confirm uxc auth credential info thegraph succeeds
  • confirm uxc auth binding match https://subgraphs.mcp.thegraph.com/sse resolves to thegraph
  • rerun thegraph-mcp-cli -h

Tested Real Scenario

The following flow was exercised successfully through uxc against the live endpoint:

• search uniswap subgraphs
• compare candidates with get_deployment_30day_query_counts
• select the highest-volume candidate
• fetch schema for the chosen subgraph
• execute a minimal _meta GraphQL query

The selected candidate in that run was:

• subgraph ID: 5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV
• deployment IPFS hash: QmTZ8ejXJxRo7vDBS4uwqBeGoxLSWbhaA7oXa1RvxunLy7

The minimal verified query shape was:

{
  _meta {
    deployment
    hasIndexingErrors
  }
}

References

• Invocation patterns:
  • references/usage-patterns.md