TronGrid MCP Server Guide

1. Introduction

TronGrid MCP Server is a service based on the Model Context Protocol (MCP) that exposes the query and operation capabilities on TRON blockchain as standardized MCP tools. This enables AI clients (such as Claude, Cursor, custom Agents, etc.) to directly interact with TRON network.

2. Quick Start

MCP Service URL

Protocol

• MCP Protocol Version: 2025-11-25
• Transport Protocol: Streamable HTTP

3. Client Configuration

3.1 Claude Desktop

Edit the configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trongrid": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.trongrid.io/mcp"
      ]
    }
  }
}

To pass an API Key:

{
  "mcpServers": {
    "trongrid": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.trongrid.io/mcp",
        "--header",
        "TRON-PRO-API-KEY:YOUR_API_KEY"
      ]
    }
  }
}

3.2 Claude Code

Option 1: CLI Command

claude mcp add --transport http trongrid https://mcp.trongrid.io/mcp

Option 2: Project Configuration File

Create .mcp.json in the project root directory:

{
  "mcpServers": {
    "trongrid": {
      "type": "http",
      "url": "https://mcp.trongrid.io/mcp"
    }
  }
}

4. MCP Protocol Basics

MCP uses Streamable HTTP for transport, with all communication performed via the POST /mcp endpoint. The protocol is stateful and requires a sequential handshake:

┌──────────┐                      ┌──────────┐
│  Client  │                      │  Server  │
└────┬─────┘                      └────┬─────┘
     │  1. initialize                  │
     │ ──────────────────────────────► │
     │ ◄── mcp-session-id ──────────── │
     │                                 │
     │  2. notifications/initialized   │
     │ ──────────────────────────────► │
     │ ◄── 202 Accepted ────────────── │
     │                                 │
     │  3. tools/list                  │
     │ ──────────────────────────────► │
     │ ◄── tool list ───────────────── │
     │                                 │
     │  4. tools/call                  │
     │ ──────────────────────────────► │
     │ ◄── tool execution result ───── │
     └                                 ┘

Header requirements are shown below; requests after the handshake must also include the session ID and negotiated protocol version:

5. Manual Testing with curl

Step 1 — Initialization (Obtain Session ID)

curl -v -X POST https://mcp.trongrid.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "1.0" }
    }
  }'

Find the mcp-session-id in the response, and read the negotiated version from result.protocolVersion in the response JSON. Save them as <your-session-id> and <protocal-version> for subsequent requests.

Step 2 — Send initialized Notification

curl -X POST https://mcp.trongrid.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <your-session-id>" \
  -H "MCP-Protocol-Version: <protocal-version>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }'

A return of 202 Accepted indicates success.

Step 3 — View Available Tools

curl -X POST https://mcp.trongrid.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <your-session-id>" \
  -H "MCP-Protocol-Version: <protocal-version>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Step 4 — Call a Tool

Take querying block statistics as an example:

curl -X POST https://mcp.trongrid.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <your-session-id>" \
  -H "MCP-Protocol-Version: <protocal-version>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "getBlockStatistics",
      "arguments": { "blockNum": 68000000 }
    }
  }'

6. Available Tool Categories

The server exposes a total of 149 MCP tools, covering major queries and operations on the TRON network:

6.1 TronGrid API Query Tools (18 tools)

Query on-chain data through the TronGrid API.

Blocks (1)

Accounts (6)

Assets (3)

Contracts (3)

Events (4)

TRC-20 Tokens (1)

6.2 Wallet Operation Tools (73 tools)

Full Node /wallet/* API endpoints for transaction creation & broadcast, account management, resource staking & delegation, smart contracts, Super Representatives, and governance proposals.

Address Validation & Transaction Broadcast (3)

Account Management (5)

TRX Transfer (1)

Account Resource Queries (2)

Resource Staking & Delegation — Stake 1.0 (4)

Resource Staking & Delegation — Stake 2.0 (11)

Block Queries (2)

Transaction Queries (5)

Network & Chain Parameters (5)

Other Chain Queries (1)

TRC-10 Asset Management (11)

Smart Contracts (9)

Super Representative (SR) Management (8)

SR Listing (1)

Governance Proposals (5)

6.3 WalletSolidity Read-Only Tools (25 tools)

Read data from the confirmed (irreversible) Solidity node, ensuring data finality. All tool names are prefixed with solidity.

Account (1)

Transaction Queries (4)

Block Queries (1)

Resource Delegation Queries (7)

Node & Chain Info (2)

Smart Contracts (2)

TRC-10 Asset Queries (5)

Super Representative Queries (3)

6.4 JSON-RPC Tools (33 tools)

Ethereum-compatible JSON-RPC API methods for developers transitioning from the Ethereum ecosystem.

Accounts & Balances (1)

Block Operations (7)

Transaction Operations (6)

Contracts & Storage (4)

Filters & Logs (6)

Chain & Network Info (9)

7. Integrating with AI Clients

Direct Connection Mode (Clients Supporting Streamable HTTP)

Add the following configuration to your MCP client configuration file:

{
  "mcpServers": {
    "trongrid-mcp": {
      "url": "https://mcp.trongrid.io/mcp"
    }
  }
}

Bridging via mcp-remote (Claude Code, etc.)

For clients that do not directly support Streamable HTTP (like Claude Code), you can use mcp-remote as a bridge:

{
  "mcpServers": {
    "mcp-server-trongrid": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.trongrid.io/mcp"]
    }
  }
}

8. FAQ

Q: Tool call returns 405 Method Not Allowed?

A: The session may have expired or become invalid. Please re-run the initialize handshake process.

Q: Receiving TronGrid API rate limit errors?

A: pass your API Key via the TRON-PRO-API-KEY request header.

Q: curl request returns no data?

A: Ensure the request header includes Accept: application/json, text/event-stream, which is mandatory for the Streamable HTTP protocol.

Related Resources

• AI agent skills — pre-built natural-language workflows built on this MCP server
• CLI — trongrid-cli for read-side TRON queries from the terminal
• TronGrid V1 API overview — the underlying API reference