> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavchain.safeney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read live blockchain data with AI

> Connect a local read-only MCP server to Tavchain Testnet to inspect blocks, balances, transaction receipts and contract state from your AI editor.

Connect your coding assistant to Tavchain's public RPC through the community `evm-rpc-mcp` reader. It can inspect blockchain data without a wallet, private key or node installation.

## Connect your agent

The examples below cover four clients. For another MCP-compatible application or agent framework, use **Other clients** to enter the connection settings manually.

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and make sure `uvx` is available to your client. The setup below requests Python 3.12 and pins the reader and MCP SDK to compatible versions. uv may download Python and packages on first use.

> [tab] Codex
>
> Run this command in your terminal:
>
> ```bash theme={null}
> codex mcp add tavchain-chain -- uvx --python 3.12 --with mcp==1.30.0 --from evm-rpc-mcp==0.1.0 evm-rpc-mcp --rpc-url https://api.testnet.tavchain.safeney.com/
> ```
>
> Run `codex mcp list` to check the configuration.

> [tab] Claude Code
>
> Run this command from your project directory:
>
> ```bash theme={null}
> claude mcp add --transport stdio tavchain-chain -- uvx --python 3.12 --with mcp==1.30.0 --from evm-rpc-mcp==0.1.0 evm-rpc-mcp --rpc-url https://api.testnet.tavchain.safeney.com/
> ```
>
> Open Claude Code and check the server with `/mcp`.

> [tab] Cursor
>
> Add this entry to `.cursor/mcp.json`, preserving any existing servers:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "tavchain-chain": {
>       "command": "uvx",
>       "args": [
>         "--python", "3.12",
>         "--with", "mcp==1.30.0",
>         "--from", "evm-rpc-mcp==0.1.0",
>         "evm-rpc-mcp",
>         "--rpc-url", "https://api.testnet.tavchain.safeney.com/"
>       ]
>     }
>   }
> }
> ```
>
> Enable the server in Cursor's MCP settings.

> [tab] VS Code
>
> Add this entry to `.vscode/mcp.json`, preserving any existing servers:
>
> ```json theme={null}
> {
>   "servers": {
>     "tavchain-chain": {
>       "type": "stdio",
>       "command": "uvx",
>       "args": [
>         "--python", "3.12",
>         "--with", "mcp==1.30.0",
>         "--from", "evm-rpc-mcp==0.1.0",
>         "evm-rpc-mcp",
>         "--rpc-url", "https://api.testnet.tavchain.safeney.com/"
>       ]
>     }
>   }
> }
> ```
>
> Start the server and enable its tools in Copilot agent mode.

> [tab] Other clients
>
> In a client that supports local MCP servers, choose **stdio** and enter these settings:
>
> | Setting | Value |
> | - | - |
> | Name | `tavchain-chain` |
> | Command | `uvx` |
>
> Arguments, in order:
>
> ```json theme={null}
> [
>   "--python", "3.12",
>   "--with", "mcp==1.30.0",
>   "--from", "evm-rpc-mcp==0.1.0",
>   "evm-rpc-mcp",
>   "--rpc-url", "https://api.testnet.tavchain.safeney.com/"
> ]
> ```
>
> Enter each array item as a separate argument if your client has individual argument fields. If it requires a configuration file, use its documented schema: some clients use `mcpServers`, others use `servers`. Keep existing server entries.
>
> Enable the server, then use the connection check below. Remote-HTTP-only clients cannot launch this local stdio reader.

This launches a local stdio process when your client connects. It is not a hosted MCP URL. The client examples use the same reader configuration; Tavchain's runtime acceptance covers Linux x64 with Python 3.12.

> [!NOTE]
>
> Keep the SDK pin. Reader version 0.1.0 uses the MCP SDK 1.x API and fails to start with SDK 2.x. The commands pin the reader and SDK; other dependencies are resolved by uv.

## Check the connection

Ask your assistant:

```text theme={null}
Use tavchain-chain to call eth_chain_id first. Continue only if it returns
0xbc3ba (771002). Then read the latest block and show its number and hash.
```

Check the result against [Network information](https://docs.tavchain.safeney.com/tavchain/network.md). This reader does not enforce an expected chain ID automatically.

Try these tasks next:

| Task | Prompt |
| - | - |
| Check a transaction | "Check this transaction hash on Tavchain. Show its receipt status and block number. If the receipt is null, say the result is not yet established." |
| Read a balance | "Read this public address's native balance on Tavchain. Show the block number and convert the base units to TAV using 18 decimals." |
| Read contract state | "Read this contract on Tavchain with eth\_call using the calldata I provide. Show the block number and raw result." |

Replace the transaction hash, public address or contract input in your request with the value you want to inspect.

## What the reader can access

The reader exposes 13 tools for network identity, blocks, transactions, receipts, balances, nonces, code, storage, logs, gas price and contract calls. It has no signing or transaction-submission tool.

Some tool descriptions use Ethereum's term `wei`. On Tavchain, the base unit is `atav`: **1 TAV = 10^18 atav**. Use an explicit block number when comparing several state queries. A missing receipt is not proof of success, and an error object must not be treated as data.

Requests use the [public RPC limits](https://docs.tavchain.safeney.com/tavchain/http-api.md#usage-limits). Keep log ranges small and back off on HTTP 429. Your AI client and RPC provider receive the queries you send; keep secrets out of prompts and configuration.

## Build your own agent

Any agent with an HTTP tool or an EVM library can query Tavchain's [Ethereum JSON-RPC endpoint](https://docs.tavchain.safeney.com/tavchain/http-api.md) directly. MCP is optional. Start by checking `eth_chainId` returns `0xbc3ba`, then use the documented methods for [balances](https://docs.tavchain.safeney.com/tavchain/api/account.md), [receipts](https://docs.tavchain.safeney.com/tavchain/api/transaction.md) and contract calls.

If your agent framework has an MCP client, give it the same stdio command and arguments shown under **Other clients**. These connection settings do not grant wallet access or signing authority.

## Troubleshooting

* **uvx not found:** install uv and restart your editor so it picks up the updated PATH.
* **FastMCP import error:** check that the setup includes `--with mcp==1.30.0`.
* **Wrong chain ID:** stop using the results and check the configured RPC URL.
* **No result or RPC error:** inspect the returned error and [RPC troubleshooting](https://docs.tavchain.safeney.com/tavchain/troubleshooting.md).

Use [Docs for AI](https://docs.tavchain.safeney.com/tavchain/ai-tools.md) alongside this reader when you want your assistant to consult Tavchain's guides. The documentation connection searches pages; this connection reads live blockchain data.

[Upstream package](https://pypi.org/project/evm-rpc-mcp/) · [Ethereum JSON-RPC](https://docs.tavchain.safeney.com/tavchain/http-api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.