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

> Discover Arbitrum MCP Server trace APIs like arbtrace_call and arbtrace_replayTransaction for low-level debugging. This guide details NitroNodeClient tools for efficient troubleshooting.

- Repository: [Dewansh/arbitrum-mcp](https://github.com/dewanshparashar/arbitrum-mcp)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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)](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)](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)](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)](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)](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

```javascript
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

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

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

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

```javascript
// 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`.

```javascript
// 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.

```javascript
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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/nitro-node-client.ts) and registered via `setupHandlers()` in [`src/index.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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.