graph-agent-toolkit

An MCP server that gives AI agents live, reasoned access to on-chain data via The Graph's decentralized network — built for ETHOnline 2026, targeting The Graph's "Best AI Tooling or AI Use Case" prize track.

Why this exists

Agents that reason about on-chain activity (risk, MEV, liquidity, fraud detection) need data that is (a) live, (b) indexed and queryable, and (c) verifiable against a known-good source before the agent trusts it. Raw GraphQL passthroughs don't do reasoning — they just hand an LLM a JSON blob and hope. This toolkit does the reasoning before the agent sees the result, and it refuses to run at all against mocked or stale data.

Related MCP server: Philidor MCP Server

What it does differently

• Boot canary, not a config flag. The server queries a known-live subgraph (Uniswap V3 mainnet) at startup and refuses to serve any tool if that canary fails. A "0 pools" or unreachable Gateway is treated as broken, not empty.

• Tools reason over the data, they don't dump it. graph_pool_risk_snapshot returns swap count, net directional flow, and largest-single-swap concentration — computed, not queried-and-forwarded.

• No API key baked in, ever. THEGRAPH_API_KEY is read from the environment only; the client throws (loudly) if it's missing, rather than silently degrading.

Architecture

src/graph-client.js   thin Gateway client + canaryQuery() — proves the key is live
src/tools.js          tool definitions: schema + real computation over the query result
src/server.js         MCP server wiring (stdio transport); runs the canary before serving
skill/                AgentSkill wrapper so any OpenClaw-style agent can call this toolkit

Setup

npm install
export THEGRAPH_API_KEY=<your Subgraph Studio API key>   # thegraph.com/studio
npm start

On boot the server runs canaryQuery() against Uniswap V3 mainnet. If your key works, you'll see a factory poolCount > 0 and the server starts. If not, it exits with a clear error — it will never silently fall back to fake data.

Tools exposed

graph_pool_risk_snapshot

Input: { poolId: "0x...", swapLimit?: number } (default 50, max 500)

Pulls the most recent N swaps for a Uniswap V3 pool and computes:

• swapCount, totalVolumeUSD, largestSingleSwapUSD

• concentrationRatio — largest single swap as a fraction of total window volume, plus a concentrationFlag ("HIGH" above 0.3 — possible whale/manipulation signal, else "normal")

• directionalBiasPct — what fraction of swaps pushed the pool the same direction

This is meant as a building block: an agent asking "is this pool being manipulated right now?" gets a computed answer, not a page of raw swap rows to parse itself.

graph_factory_health

No input required. Returns live protocol-wide Uniswap V3 stats (poolCount, txCount, totalVolumeUSD, totalValueLockedUSD) — useful as a cheap sanity check that the data source is live and current before trusting a pool-level result.

Spec / AI-use disclosure

Built with Claude Code (Anthropic) acting as the primary developer, directed by Jiggy (project owner) and Cadence (agent). All prompts and planning notes for this project are tracked in this repo's commit history — no separate spec files were used beyond normal commit messages, which describe intent and rationale for each change.

License

MIT