---
title: Thru MCP Overview
description: Connect an AI agent to the Thru MCP server at mcp.thru.org for live
  blocks, transactions, accounts, account history, and on-chain program ABIs.
source_url:
  html: https://thru.org/docs/api-ref/thru-mcp/overview/
  md: https://thru.org/docs/api-ref/thru-mcp/overview.md
---

# 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

- 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](https://thru.org/docs/cli-reference/overview.md) or an SDK
- you need a typed application integration: use the [gRPC API](https://thru.org/docs/api-ref/grpc/overview.md) or an SDK
- you are still deciding which docs to read: start with [Build with LLMs](https://thru.org/docs/getting-started/build-with-an-llm.md)

## Endpoint

```text
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](#authentication).

## 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

1. Install the CLI:

   ```bash
   npm i -g thru
   ```

2. Create an agent key for your client. `<client>` is one of `claude-code`, `codex`, `cursor`, or `vscode`:

   ```bash
   thru auth keys create --name <name> --agent <client>
   ```

3. Approve the key in your browser. The CLI opens an approval page on [Thru Developers](https://dev.thru.org/).

   - 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:

| `--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 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](#configure-a-client-by-hand).

For every flag, see [Auth commands](https://thru.org/docs/cli-reference/auth-commands.md#create-a-key-for-an-ai-agent).

### 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:

```bash
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.

### From the Dashboard

If you don’t use the CLI, open [Organization settings](https://dev.thru.org/organization) 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.

> **Caution:**
>
> The install command contains the key. Run it in your own terminal or paste it into your client’s configuration file. Don’t paste it into an agent chat.

### 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](https://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`:

**JSON (Cursor and similar):**

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

**VS Code mcp.json:**

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

**Codex config.toml:**

```toml
[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

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

```http
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](https://dev.thru.org/keys) or with [`thru auth keys revoke`](https://thru.org/docs/cli-reference/auth-commands.md#organization-api-keys).

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:

```json
{
  "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

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](https://thru.org/docs/api-ref/rate-limits.md) 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](https://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.

## 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:

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 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:

```json
{ "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.

## Responses and Errors

Each tool returns one text item in [TOON](https://github.com/toon-format/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:

| 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.

## Next Steps

- [Tools Reference](https://thru.org/docs/api-ref/thru-mcp/tools-reference.md): See each Thru MCP tool, its arguments, and when to use it.
- [Auth commands](https://thru.org/docs/cli-reference/auth-commands.md): Create, list, and revoke API keys from the thru CLI.
- [Build with LLMs](https://thru.org/docs/getting-started/build-with-an-llm.md): Install the Thru skill and pick the right docs for agent-driven Thru development.
