Agents

A contract's history, in your agent, in about a minute.

Nuthatch ships the agent surface in the binary: an MCP server, and a skill and an llms.txt written into every nest init scaffolds. Four commands take Claude Code or Cursor from nothing to asking questions of a contract's events on your own machine. There is no account, no API key and no hosted service in the loop. Every command below was run against Nuthatch 5.16.0 on 3 November 2026.

1 · install
The installer fetches the release binary for your platform, checks its SHA-256 and puts it in ~/.local/bin. A fresh macOS shell lacks that directory on its PATH, hence the second line. Other routes.

$ curl -fsSL https://nuthatch-indexer.com/install.sh | sh

$ export PATH="$HOME/.local/bin:$PATH"
2 · init
Point it at a contract. It resolves the ABI, makes one table per event, and writes the files an agent reads. This one took 5 seconds.

$ nuthatch init 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain mainnet
3 · run
--backfill 300 starts 300 blocks behind the tip, so there are rows within seconds. The API listens on 127.0.0.1:8288.

$ nuthatch dev --backfill 300
4 · connect
In a second terminal, register the MCP server with Claude Code. It speaks stdio and bridges to the running nest.

$ claude mcp add nuthatch -- nuthatch mcp --url http://127.0.0.1:8288

init, 5.16.0, trimmed

$ nuthatch init 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain mainnet
→ resolving ABI for 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 on mainnet…
  · proxy → implementation 0x43506849d7c04f9138d1a2050bbf3a0c054402dd
  ✓ ABI resolved via Sourcify
  · alias fiat_token_v2_2
  ✓ deployed at block 6082465
✓ scaffolded nest 'usdc' (1 contract(s), 17 table(s)) in .
    nuthatch.toml              config
    abis/                      resolved ABIs
    schema.json                decoded tables + columns
    semantic.toml              what the data means (edit freely)
    views/                     authored SQL derivations (a commented starter to uncomment)
    llms.txt                   how an AI agent queries this index
    .claude/skills/nuthatch/   Claude Code skill (offline, no phone-home)

Cursor and the others

Every MCP client takes the same entry; only the file differs. For Cursor it goes in .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project. Claude Code also reads it from .mcp.json at the project root. If nuthatch is not on the client's PATH, use the absolute path, which nuthatch mcp --print-config prints for you along with the claude mcp add line.

.cursor/mcp.json or .mcp.json

{
  "mcpServers": {
    "nuthatch": { "command": "nuthatch", "args": ["mcp", "--url", "http://127.0.0.1:8288"] }
  }
}

What the agent gets

The tool menu follows what the nest holds. The USDC nest above answered tools/list with ten tools; a nest that is not a token has no balance or top_balances, so the agent is never offered a tool that can only return nothing. A failed query comes back with a fix hint drawn from the real schema, and a sql answer ends with the block it is current to.

status: contract, chain, last and sealed block
schema: the data model and what each table means; read it first
tables: the exact tables and columns
table: recent rows of one table
sql: read-only SQL over the tip and sealed history, with provenance
explain: checks a query binds before it runs
entity: one entity by id
diff: what happened in a block range, in fixed sentences
balance: one holder, on a token nest
top_balances: the largest holders, on a token nest

The skill and llms.txt

init writes .claude/skills/nuthatch/SKILL.md and llms.txt into the nest. Both are generated from the decode registry, so they name the tables and columns this nest actually has, and both tell the agent to use the MCP tools when they are there and the HTTP API when they are not. nuthatch schema regenerates them after you edit the config by hand. Open the agent in the nest's directory and it finds them without being told.

Building nests, rather than querying one, is a different job with its own skill: the builder skill teaches an agent to drive the CLI, and its flag reference is generated from the binary and checked in CI.

What it does not do

The MCP server runs no model and holds no data of its own: it is a bridge to a running nuthatch dev, so with no nest running every tool fails. The agent writes queries; nothing it says is stored, because no model output sits in the data path. With --backfill 300 the nest holds 300 blocks, so a balance it reports is the net flow over those blocks, not a holder's balance. For whole history, drop the flag and give it your own RPC with --rpc.

Claude Code 2.1.317 registered the server with the line in step 4. The Cursor entry follows the format the MCP docs give; we have not run it in Cursor for this page.