Trace APIs Available in the Arbitrum MCP Server for Debugging: A Complete Guide

The Arbitrum MCP Server exposes eight trace-related tools—including arbtrace_call, arbtrace_replayTransaction, and arbtrace_filter—through the NitroNodeClient class to enable low-level execution debugging of Arbitrum nodes.

The dewanshparashar/arbitrum-mcp repository implements a Model‑Context‑Protocol (MCP) server that wraps Arbitrum Nitro node RPC endpoints, making trace APIs available in the Arbitrum MCP Server for debugging smart contract execution, state changes, and transaction failures.

Overview of Trace APIs in the Arbitrum MCP Server

Trace APIs provide granular visibility into Ethereum Virtual Machine (EVM) execution at the node level. In the Arbitrum MCP Server, these capabilities are implemented by the NitroNodeClient class in [src/clients/nitro-node-client.ts](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/nitro-node-client.ts) and exposed as callable tools in [src/index.ts](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/index.ts).

The server’s setupHandlers() method registers each trace tool, mapping incoming MCP requests to the appropriate RPC method on the underlying Nitro node.

Complete List of Trace APIs Available in the Arbitrum MCP Server

The following table summarizes every trace tool exposed by the server, including required parameters and typical debugging scenarios.

Tool Name	Description	Required Parameters	Debugging Use Case
arbtrace_call	Executes a single call on a specified block and returns trace information.	callArgs (object), optional traceTypes (array), optional blockNumOrHash (string)	Debug a single contract call, inspect the full call stack, or analyze state diffs.
arbtrace_callMany	Executes multiple calls in a batch on the same block, returning an array of trace results.	calls (array of call objects), optional blockNumOrHash (string)	Efficiently obtain traces for many calls without repeated RPC round‑trips.
arbtrace_replayBlockTransactions	Replays all transactions in a block and returns their traces.	blockNumOrHash (string), optional traceTypes (array)	Inspect every transaction in a block for block‑level debugging or analytics.
arbtrace_replayTransaction	Replays a single transaction and returns its trace information.	txHash (string), optional traceTypes (array)	Deep dive into the execution of a specific transaction.
arbtrace_transaction	Retrieves previously recorded trace data for a transaction without replaying.	txHash (string)	Quickly fetch trace data if it was already stored by the node.
arbtrace_get	Extracts a specific piece of trace data from a transaction using a path array.	txHash (string), path (array of strings)	Pull out a particular field (e.g., result, error) from a transaction’s trace.
arbtrace_block	Returns trace information for all transactions in a block without replay.	blockNumOrHash (string)	Get a snapshot of trace data already collected for a block.
arbtrace_filter	Filters traces across blocks and transactions based on a filter object.	filter (object)	Search for traces matching specific criteria (address, topics, etc.).

Architecture and Implementation Details

Nitro Node Client

The [src/clients/nitro-node-client.ts](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/nitro-node-client.ts) file contains the NitroNodeClient class, which encapsulates the raw RPC calls to an Arbitrum Nitro node. Each trace method maps to a specific JSON‑RPC endpoint:

• traceCall() → arbtrace_call
• traceCallMany() → arbtrace_callMany
• replayBlockTransactions() → arbtrace_replayBlockTransactions
• replayTransaction() → arbtrace_replayTransaction
• traceTransaction() → arbtrace_transaction
• traceGet() → arbtrace_get
• traceBlock() → arbtrace_block
• traceFilter() → arbtrace_filter

Tool Registration and Request Flow

In [src/index.ts](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/index.ts), the setupHandlers() method registers each trace tool with the MCP server. When a client invokes a tool, the handler:

1. Resolves the RPC URL using a default endpoint, an explicit rpcUrl parameter, or a chainName lookup via [src/services/chain-lookup.ts](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/services/chain-lookup.ts).
2. Instantiates NitroNodeClient with the resolved URL.
3. Executes the corresponding client method (e.g., nodeClient.traceCall(...)).
4. Returns the JSON‑encoded result as a text‑only MCP response.

Practical Code Examples for Arbitrum MCP Trace Debugging

The following examples demonstrate how to invoke trace APIs using the MCP JavaScript SDK. These assume you have initialized the client; you may optionally specify rpcUrl or chainName in each request to override defaults.

Initializing the MCP Client

import { Server, StdioServerTransport } from "@modelcontextprotocol/sdk/server";
import { CallToolRequestSchema } from "@modelcontextprotocol/sdk/types";

const server = new Server(
  { name: "arbitrum-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);
const transport = new StdioServerTransport(server);
await transport.start();

Helper Function for Tool Calls

async function callTool(name, args) {
  const response = await transport.callTool({
    name,
    arguments: args,
  });
  console.log(JSON.parse(response.content[0].text));
}

Debugging Single Contract Calls with arbtrace_call

Use arbtrace_call to simulate a transaction and inspect the execution trace without submitting it to the network.

await callTool("arbtrace_call", {
  callArgs: {
    from: "0x1111111111111111111111111111111111111111",
    to: "0x2222222222222222222222222222222222222222",
    data: "0x", // Empty data indicates an ETH transfer
    value: "0xDE0B6B3A7640000", // 1 ETH in wei
    gas: "0x5208",
    gasPrice: "0x3B9ACA00",
  },
  traceTypes: ["trace", "stateDiff"],
  blockNumOrHash: "latest",
});

Batch Debugging with arbtrace_callMany

Efficiently trace multiple calls in a single request to minimize RPC round‑trips.

await callTool("arbtrace_callMany", {
  calls: [
    {
      from: "0xaaa...aaa",
      to: "0xbbb...bbb",
      data: "0x",
      value: "0x0",
    },
    {
      from: "0xccc...ccc",
      to: "0xddd...ddd",
      data: "0xabcdef",
    },
  ],
  blockNumOrHash: "latest",
});

Replaying Historical Transactions

Inspect the exact execution path of a confirmed transaction using arbtrace_replayTransaction, or analyze an entire block with arbtrace_replayBlockTransactions.

// Single transaction replay
await callTool("arbtrace_replayTransaction", {
  txHash: "0x1234abcd...ef",
  traceTypes: ["trace", "stateDiff"],
});

// Full block replay
await callTool("arbtrace_replayBlockTransactions", {
  blockNumOrHash: "0x10A5F",
  traceTypes: ["trace"],
});

Retrieving Stored Trace Data

When the node has already cached trace data, use arbtrace_transaction or arbtrace_block to fetch it instantly without replay overhead. For targeted data extraction, use arbtrace_get.

// Fetch stored trace for a transaction
await callTool("arbtrace_transaction", {
  txHash: "0x1234abcd...ef",
});

// Extract specific field from trace
await callTool("arbtrace_get", {
  txHash: "0x1234abcd...ef",
  path: ["result", "output"],
});

// Get all stored traces for a block
await callTool("arbtrace_block", {
  blockNumOrHash: "0x10A5F",
});

Filtering Traces Across Blocks

Use arbtrace_filter to search for traces matching specific addresses or topics, similar to eth_getLogs but for execution traces.

await callTool("arbtrace_filter", {
  filter: {
    fromBlock: "0x10A00",
    toBlock: "0x10AFF",
    address: "0x2222222222222222222222222222222222222222",
    // Optional: topics, after, count, etc.
  },
});

Summary

• The Arbitrum MCP Server exposes eight distinct trace APIs that map directly to Arbitrum Nitro node RPC endpoints, enabling deep execution debugging.
• All trace tools are implemented in the NitroNodeClient class within src/clients/nitro-node-client.ts and registered via setupHandlers() in src/index.ts.
• Single-call debugging uses arbtrace_call, while batch operations use arbtrace_callMany to minimize latency.
• Historical analysis relies on arbtrace_replayTransaction and arbtrace_replayBlockTransactions to re-execute and inspect past transactions.
• Data retrieval methods like arbtrace_transaction, arbtrace_block, and arbtrace_get provide fast access to cached trace data without replay overhead.
• Filtering capabilities via arbtrace_filter allow forensic searching across block ranges by address and topics.

Frequently Asked Questions

What is the difference between arbtrace_call and arbtrace_replayTransaction?

arbtrace_call simulates a hypothetical transaction against a specific block state without requiring an actual transaction hash, making it ideal for testing contract interactions before submission. arbtrace_replayTransaction requires a valid transaction hash and re-executes that exact historical transaction to show what actually occurred on-chain, including any failures or state changes.

How do I filter traces by specific contract addresses?

Use the arbtrace_filter tool with a filter object containing the address field. You can specify a single address or an array of addresses, along with fromBlock and toBlock parameters to narrow the search range. This functions similarly to eth_getLogs but returns execution traces instead of event logs.

Can I use these trace APIs on Arbitrum Sepolia testnet?

Yes, the Arbitrum MCP Server supports multiple networks through the ChainLookupService in src/services/chain-lookup.ts. When invoking any trace tool, you can pass a chainName parameter (such as "arbitrum-sepolia") or a custom rpcUrl pointing to a Sepolia Nitro node endpoint.

What trace types are supported in the traceTypes parameter?

The optional traceTypes parameter accepts an array of strings that determine the verbosity and content of the returned trace. Common values include "trace" (the default execution trace), "stateDiff" (state changes caused by the transaction), and "vmTrace" (low-level VM execution steps). Not all methods support all types; for example, arbtrace_call and arbtrace_replayTransaction accept traceTypes, while arbtrace_transaction returns stored data without replay options.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}