Rango Transaction Debugger — MCP Server

An MCP (Model Context Protocol) server that gives AI assistants the ability to analyze blockchain transactions across EVM, Solana, and TON networks.

Connect it to Claude, Cursor, Windsurf, or any MCP-compatible client and start debugging transactions in natural language — no API keys required on your end.

---

Supported Networks

Ecosystem	Networks
EVM	Ethereum, Polygon, Arbitrum, Optimism, Base, BSC
Solana	Mainnet, Devnet
TON	Mainnet, Testnet

---

Tools

Tool	Description
debug_transaction	Full pipeline analysis: call tree, token flows, semantic actions, risk flags, failure reasons, and an AI narrative. Supports EVM, Solana, and TON.
resolve_rango_swap	Resolve a Rango cross-chain swap by swap ID — returns all steps, statuses, and per-chain transaction hashes.
ask_question	Ask a follow-up question about a previously analyzed transaction.

---

Skills (Prompt Templates)

Skills are pre-built prompt templates that guide the AI through complex workflows. Invoke them from your MCP client's slash menu or prompt library.

Skill	Use When
debug_evm_transaction	Analyzing any EVM transaction — swap, bridge, NFT mint, contract call
debug_solana_transaction	Analyzing Solana transactions — SPL transfers, Jupiter swaps, staking
debug_ton_transaction	Analyzing TON transactions — Jetton transfers, DeDust/STON.fi swaps
trace_rango_swap	Tracing a complete Rango cross-chain swap end-to-end across all chain legs
investigate_failed_transaction	Root-cause analysis of a failed transaction, with plain-English explanation

Each skill follows a structured prompt format covering task context, tone, background data, rules, examples, step-by-step reasoning instructions, output formatting, and a prefilled response opener.

---

Connecting to a Hosted Instance

If you have been given a server URL and API key, add the following to your MCP client configuration and you're ready to go — no local setup required.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "rango-debugger": {
      "url": "https://your-mcp-server-url/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor / Windsurf — add the same entry under MCP settings in your IDE preferences.

---

Self-Hosting

Prerequisites

• Node.js 20+
• A running instance of the Rango Transaction Debugger backend (or use the hosted backend)

Local (stdio)

Suitable for use with Claude Desktop or Cursor when running everything on your own machine.

git clone https://github.com/0x4rde/rango-transaction-debugger.git
cd rango-transaction-debugger

npm install
cp .env.example .env
# Edit .env: set BACKEND_URL to your backend instance

npm run build

Then add to your MCP client config:

{
  "mcpServers": {
    "rango-debugger": {
      "command": "node",
      "args": ["/absolute/path/to/rango-transaction-debugger/dist/index.js"]
    }
  }
}

HTTP Server (shared / team use)

Run the HTTP server so your whole team can connect without local setup.

cp .env.example .env
# Edit .env:
#   BACKEND_URL=https://your-backend-url
#   MCP_API_KEY=<generate with: openssl rand -hex 32>
#   PORT=3100

npm run build
npm run start:server

Or with Docker:

docker compose up -d

The MCP endpoint will be available at http://localhost:3100/mcp.
Put it behind a reverse proxy (nginx, Traefik, Caddy) for HTTPS.

---

Environment Variables

Variable	Default	Description
BACKEND_URL	(required)	URL of the Rango Transaction Debugger backend API
MCP_API_KEY	(none)	Bearer token for authentication. Required when exposing the server over the internet.
PORT	3100	HTTP port for the server entry point

---

Example Usage

Once connected, you can talk to your AI assistant naturally:

Debug this transaction: 0xabc123...

Use the trace_rango_swap skill for swap ID: a1b2c3d4-...

Why did this transaction fail? 0xdef456...

What tokens were transferred in 0x789abc... on Arbitrum?

---

License

MIT