Thru MCP Overview
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.
Use This When
Section titled “Use This When”- 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.orglink 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
Endpoint
Section titled “Endpoint”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.
Connect Your Agent
Section titled “Connect Your Agent”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.
With the Thru CLI
Section titled “With the Thru CLI”-
Install the CLI:
Terminal window npm i -g thru -
Create an agent key for your client.
<client>is one ofclaude-code,codex,cursor, orvscode:Terminal window thru auth keys create --name <name> --agent <client> -
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 loginfirst.
-
Reload MCP servers in your client, for example by starting a new session. The
thrutools then appear.
The CLI installs the key without printing it, so the key stays out of your agent’s transcript:
--agent | What the CLI does |
|---|---|
claude-code | Runs claude mcp add --scope user --transport http thru https://mcp.thru.org/mcp with the Authorization header. |
codex | Adds [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. |
cursor | Adds mcpServers.thru to ~/.cursor/mcp.json. |
vscode | Adds 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 thethru-best-practicesskill withnpx skills add https://thru.org. Pass--no-skillto 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.
When an AI Agent Runs the Command
Section titled “When an AI Agent Runs the Command”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:
thru auth keys create --name <name> --agent claude-code --no-wait --jsonthru auth keys create --resume- The first command prints
verification_uri_completeand exits. The agent shows that link to you. - You open the link and approve the key.
- The agent runs
thru auth keys create --resume, which installs the key with the options given to--no-wait. - Reload MCP servers in the client.
From the Dashboard
Section titled “From the Dashboard”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.
Configure a Client by Hand
Section titled “Configure a Client by Hand”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_..." } } }}{ "servers": { "thru": { "type": "http", "url": "https://mcp.thru.org/mcp", "headers": { "Authorization": "Bearer thru_..." } } }}[mcp_servers.thru]url = "https://mcp.thru.org/mcp"bearer_token_env_var = "THRU_MCP_API_KEY"Set THRU_MCP_API_KEY in the environment Codex runs in. Use a separate variable from THRU_API_KEY, which the thru CLI sends with its own RPC calls.
Keep keys out of source control and shared configuration files.
Authentication
Section titled “Authentication”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
--agentare tagged as agent keys. You see them, and can revoke them, at dev.thru.org/keys or withthru 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}Rate Limits
Section titled “Rate Limits”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 byRetry 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
429with aRetry-Afterheader and the same advice.
Networks
Section titled “Networks”The server reads from these networks:
network | RPC |
|---|---|
betanet (default) | https://rpc.betanet.thru.org |
Pick the network in one of three ways. The first one present wins:
- Per tool call. Every tool takes an optional
networkargument. - From an explorer link. A
scan.thru.orglink’s?network=selects the network. If you also passnetwork, the two must match. - Per connection. Add
?network=to the endpoint, for examplehttps://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 Links
Section titled “Explorer Links”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_linkreads the block, transaction, or account behind anyhttps://scan.thru.org/block/<slot>,/tx/<signature>, or/address/<address>link.get_block,get_transaction,get_account,list_account_transactions,get_program_abi, andsearchalso 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 withAccept: text/markdown. https://scan.thru.org/llms.txtandhttps://scan.thru.org/.well-known/mcp/server-card.jsondescribe the server.
Responses and Errors
Section titled “Responses and Errors”Each tool returns one text item in TOON, a compact encoding of JSON for language models. It holds:
data: the structured resultsummary: a one-line, plain-English descriptionlinks: absolute explorer URLs for the entities in the result
Errors come back in two forms:
| Problem | How 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 network | A 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 failure | A tool result with isError: true and a short message. Messages never include keys. |
| An unknown tool name or a malformed request | A 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.