Skip to content

Thru MCP Overview

View as Markdown

The Thru MCP server gives AI agents live Thru chain data: blocks, transactions, accounts, account history, and on-chain program ABIs. Use it when an agent needs current chain state instead of guessing from stale context or scraping explorer pages.

The server is read-only. No tool signs or sends transactions. It works without an API key, on a shared free tier with lower limits; with your own key, your agent gets your organization’s limits.

  • you want an agent to inspect a block, transaction, account, or program ABI
  • you want to debug deployed behavior on betanet
  • you want recent chain activity or an account’s transaction history
  • you want to classify an unknown ta..., ts..., or slot value
  • someone shares a scan.thru.org link with your agent

Choose another interface when:

  • you need to send transactions or change chain state: use the CLI Reference or an SDK
  • you need a typed application integration: use the gRPC API or an SDK
  • you are still deciding which docs to read: start with Build with LLMs
https://mcp.thru.org/mcp
  • Transport: streamable HTTP. The server is stateless: it issues no session IDs and answers with JSON.
  • Server name: thru.
  • Authentication: optional. Send Authorization: Bearer thru_<key> for your own limits; without it, requests run on the shared free tier. See Authentication.

The thru CLI creates an API key for your agent and installs it into the agent’s MCP configuration. You approve each key in your browser.

  1. Install the CLI:

    Terminal window
    npm i -g thru
  2. Create an agent key for your client. <client> is one of claude-code, codex, cursor, or vscode:

    Terminal window
    thru auth keys create --name <name> --agent <client>
  3. Approve the key in your browser. The CLI opens an approval page on Thru Developers.

    • Sign in with GitHub, Google, or X. If you have no account, signing in creates one.
    • Choose the organization the key belongs to, then approve.
    • You don’t need to run thru auth login first.
  4. Reload MCP servers in your client, for example by starting a new session. The thru tools then appear.

The CLI installs the key without printing it, so the key stays out of your agent’s transcript:

--agentWhat the CLI does
claude-codeRuns claude mcp add --scope user --transport http thru https://mcp.thru.org/mcp with the Authorization header.
codexAdds [mcp_servers.thru] to ~/.codex/config.toml (or $CODEX_HOME/config.toml), reading the key from THRU_MCP_API_KEY. It saves the key to an owner-only file under ~/.thru/cli and prints the export THRU_MCP_API_KEY=... line to add to your shell profile.
cursorAdds mcpServers.thru to ~/.cursor/mcp.json.
vscodeAdds servers.thru to VS Code’s user mcp.json.
  • The CLI keeps the other entries in these files and saves the previous file as <file>.bak.
  • With --agent, the CLI also installs the thru-best-practices skill with npx skills add https://thru.org. Pass --no-skill to skip it.
  • For any other client, or with --print, the CLI prints the key once together with the MCP URL. Configure the client by hand.

For every flag, see Auth commands.

An agent waits for each command to exit, so it can’t show the approval link while thru auth keys create is waiting. Split the command in two:

Terminal window
thru auth keys create --name <name> --agent claude-code --no-wait --json
thru auth keys create --resume
  1. The first command prints verification_uri_complete and exits. The agent shows that link to you.
  2. You open the link and approve the key.
  3. The agent runs thru auth keys create --resume, which installs the key with the options given to --no-wait.
  4. Reload MCP servers in the client.

If you don’t use the CLI, open Organization settings in Thru Developers, select Create key, check For an AI agent, and pick your client. After you create the key, the dashboard shows it once inside the install command for Claude Code, Codex, Cursor, or VS Code.

Any Thru API key works with the MCP, including keys from --print and keys created at dev.thru.org/keys. Configure an HTTP MCP server named thru that sends the key as a bearer token. To try the shared free tier first, leave out headers:

{
"mcpServers": {
"thru": {
"type": "http",
"url": "https://mcp.thru.org/mcp",
"headers": { "Authorization": "Bearer thru_..." }
}
}
}

Keep keys out of source control and shared configuration files.

A key is optional. To use your own, send it on every request:

Authorization: Bearer thru_...
  • Without a key: requests run on the shared free tier. The server makes their RPC calls with a key shared by every caller without one. Each caller is limited per IP address, and the free tier has lower limits overall. Like the explorer, it is meant for trying the server and for light use.
  • With your key: the server forwards your key on every RPC call it makes for a tool call. The Thru RPC edge checks the key and applies your organization’s limits. The key is thru_ followed by 32 letters and digits.
  • The server stores nothing. Keys created with --agent are tagged as agent keys. You see them, and can revoke them, at dev.thru.org/keys or with thru auth keys revoke.

A malformed Authorization header, or an unknown or revoked key, gets HTTP 401 with WWW-Authenticate: Bearer and a JSON-RPC error that says how to fix it. A typo in a key never falls back to the free tier:

{
"jsonrpc": "2.0",
"error": {
"code": -32000,
"message": "Thru API key not recognised. Create one with `thru auth keys create --name <name> --agent <client>` (it installs the key into your agent) or at https://dev.thru.org/keys."
},
"id": null
}

Tool calls count against your key like any other RPC traffic. A tool call makes one or more RPC calls, and the edge applies your organization’s limits to each. See Rate limits and API keys for the limits and request weights.

  • With your key: when the edge rate-limits a tool call, the tool returns an error result: Rate limited by the Thru RPC edge for this API key., followed by Retry after <N> s. when the edge says how long to wait, and a link to the limits. Wait at least that long before you retry.
  • On the free tier: the error says the shared free tier is rate-limited and how to get your own key: thru auth keys create --name <name> --agent <client>, or dev.thru.org/keys.
  • Every request to the server is also limited per IP address. Over that limit, it answers HTTP 429 with a Retry-After header and the same advice.

The server reads from these networks:

networkRPC
betanet (default)https://rpc.betanet.thru.org

Pick the network in one of three ways. The first one present wins:

  1. Per tool call. Every tool takes an optional network argument.
  2. From an explorer link. A scan.thru.org link’s ?network= selects the network. If you also pass network, the two must match.
  3. Per connection. Add ?network= to the endpoint, for example https://mcp.thru.org/mcp?network=betanet, to change the default for every call on that connection.

Custom RPC endpoints are not supported. The endpoint rejects ?rpc= and unknown networks with HTTP 400 (JSON-RPC error -32602). Tools reject explorer links that use ?rpc= or ?network=custom, because custom RPC links work only in the browser explorer.

Explorer pages on scan.thru.org load their data in the browser, so an agent that fetches a page sees labels with empty values. Give the link to the MCP instead:

{ "url": "https://scan.thru.org/tx/ts...?network=betanet" }
  • open_explorer_link reads the block, transaction, or account behind any https://scan.thru.org/block/<slot>, /tx/<signature>, or /address/<address> link.
  • get_block, get_transaction, get_account, list_account_transactions, get_program_abi, and search also accept a link in place of the slot, signature, or address.
  • Tool results link back to explorer pages, for example https://scan.thru.org/tx/<signature>?network=betanet.

The explorer also points agents to the MCP:

  • Every block, transaction, and address page carries a visually hidden Using an AI agent? note in its HTML, with the exact tool call for that page. People browsing the explorer don’t see it; agents that fetch the page do.
  • Each of those pages has a Markdown version: /block/<slot>.md, /tx/<signature>.md, and /address/<address>.md, or the page URL requested with Accept: text/markdown.
  • https://scan.thru.org/llms.txt and https://scan.thru.org/.well-known/mcp/server-card.json describe the server.

Each tool returns one text item in TOON, a compact encoding of JSON for language models. It holds:

  • data: the structured result
  • summary: a one-line, plain-English description
  • links: absolute explorer URLs for the entities in the result

Errors come back in two forms:

ProblemHow it comes back
A bad argument: invalid slot, signature, or address; a link to another site or an unsupported page; an unknown network; a link whose network contradicts networkA tool result with isError: true and a message saying what to change, so the agent can fix the call and retry.
Not found, a rejected or revoked key, a rate limit, or another RPC failureA tool result with isError: true and a short message. Messages never include keys.
An unknown tool name or a malformed requestA JSON-RPC error. An unknown tool is -32602.

A rejected or revoked key returns API key rejected or revoked by the Thru RPC edge. with a hint to create a new key.