/thegraph-mcp-skill

name: thegraph-mcp-skill
description: Use The Graph Subgraph MCP through UXC via native SSE with a fixed linked command for subgraph discovery, schema retrieval, deployment selection, and GraphQL query execution with help-first inspection and explicit auth handling.

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`