How to Use arbtrace_call with the Arbitrum MCP Server: A Complete Developer Guide

The arbtrace_call tool in the Arbitrum MCP Server enables developers to simulate transaction execution and retrieve detailed traces from Arbitrum Nitro nodes by routing requests through the NitroNodeClient.traceCall() method, which forwards the call to the node's JSON-RPC endpoint and returns structured trace data.

The arbtrace_call method is essential for debugging smart contract interactions on Arbitrum, allowing you to analyze transaction traces without consuming gas or submitting transactions to the network. This guide demonstrates how to leverage arbtrace_call through the Arbitrum MCP Server (dewanshparashar/arbitrum-mcp), a Model-Context-Protocol implementation that wraps Nitro node RPC calls in a standardized tool interface.

Understanding the arbtrace_call Architecture

When you invoke the arbtrace_call tool, the request flows through a structured pipeline that abstracts the complexity of direct JSON-RPC communication with Arbitrum Nitro nodes.

Request Flow Overview

The architecture follows four distinct stages:

1. Client Request: Your application sends a CallToolRequest named arbtrace_call with arguments including callArgs (transaction data), traceTypes (array of trace formats), and optional blockNumOrHash.

2. Server Handler: In src/index.ts (lines 65-82), the setupHandlers method matches the tool name and creates a NitroNodeClient instance pointed at the resolved RPC URL.

3. RPC Execution: The NitroNodeClient.traceCall() method in src/clients/nitro-node-client.ts (lines 15-27) builds the JSON-RPC payload and calls the Nitro node's arbtrace_call method.

4. Response Handling: The trace result is wrapped in a TraceResult object and returned to the client as a text content block.

Core Components

resolveRpcUrl(chainNameOrUrl?)

This function in src/index.ts determines the final RPC endpoint by accepting either a direct URL via args.rpcUrl, a chain identifier via args.chainName (resolved through src/services/chain-lookup.ts), or falling back to a default URL configured via the set_rpc_url tool.

const rpcUrl = await this.resolveRpcUrl(
    (args.rpcUrl as string) || (args.chainName as string)
);

NitroNodeClient.traceCall()

Located in src/clients/nitro-node-client.ts, this method constructs the RPC call:

const traces = await this.makeRpcCall("arbtrace_call", [
    callArgs,
    traceTypes,
    blockNumOrHash || "latest",
]);

The makeRpcCall method handles the underlying HTTP POST to the Nitro node and parses the JSON-RPC response.

Implementing arbtrace_call in Your Application

Setting Up the Default RPC URL

Before executing traces, configure the default RPC endpoint using the set_rpc_url tool:

await server.callTool("set_rpc_url", { 
  rpcUrl: "https://arb1.arbitrum.io/rpc" 
});

This step is optional if you provide rpcUrl or chainName directly in each arbtrace_call request.

Executing the Trace Call

To simulate a transaction and retrieve traces, invoke the arbtrace_call tool with the required parameters:

const callArgs = {
  from: "0xYourAddress",
  to: "0xRecipientAddress",
  gas: "0x5208",          // 21000 gas (hex)
  gasPrice: "0x3B9ACA00", // 1 Gwei (hex)
  value: "0xDE0B6B3A7640000", // 1 ETH (hex)
  data: "0x"
};

const result = await server.callTool("arbtrace_call", {
  rpcUrl: "https://arb1.arbitrum.io/rpc", // optional if default set
  callArgs,
  traceTypes: ["trace"], // options: "stateDiff", "vmTrace", etc.
  blockNumOrHash: "latest" // optional
});

console.log(result.content[0].text);

The response contains a TraceResult object with the requested trace data, which may include execution traces, state differences, or VM traces depending on the traceTypes specified.

Using the CLI Interface

If running the MCP server as a standalone process, you can interact with it via standard input/output:

# Start the server (it will listen on stdin/stdout)

node ./dist/src/index.js

Then send JSON-RPC requests through the transport layer. The request format follows the MCP protocol:

{
  "jsonrpc": "2.0",
  "method": "callTool",
  "params": {
    "name": "arbtrace_call",
    "arguments": {
      "rpcUrl": "https://arb1.arbitrum.io/rpc",
      "callArgs": {
        "from": "0x...",
        "to": "0x...",
        "gas": "0x5208",
        "value": "0x0",
        "data": "0x"
      },
      "traceTypes": ["trace"]
    }
  },
  "id": 1
}

Key Source Files and Implementation Details

Understanding the underlying implementation helps debug issues and extend functionality:

File	Role	Key Location
src/index.ts	Request handler mapping arbtrace_call to client methods	Lines 65-82
src/clients/nitro-node-client.ts	traceCall() implementation forwarding to Nitro RPC	Lines 15-27
src/services/chain-lookup.ts	Resolves chain names to RPC URLs	Full file
README.md	General server documentation	Repository root

The setupHandlers method in src/index.ts creates the bridge between the MCP tool interface and the Nitro node client, while NitroNodeClient in src/clients/nitro-node-client.ts handles the actual JSON-RPC serialization and HTTP transport.

Summary

• arbtrace_call simulates transaction execution on Arbitrum Nitro nodes without consuming gas, returning detailed execution traces.
• The Arbitrum MCP Server wraps this functionality in a Model-Context-Protocol tool, abstracting JSON-RPC complexity through src/index.ts and src/clients/nitro-node-client.ts.
• Key components include resolveRpcUrl() for endpoint resolution and NitroNodeClient.traceCall() for RPC execution.
• You can configure the default RPC URL via set_rpc_url or pass rpcUrl/chainName per request.
• Supported trace types include "trace", "stateDiff", and "vmTrace", specified in the traceTypes array.

Frequently Asked Questions

What parameters does arbtrace_call require?

The arbtrace_call tool requires a callArgs object containing transaction fields (from, to, gas, gasPrice, value, data) and a traceTypes array specifying which trace formats to return (e.g., ["trace"]). Optional parameters include rpcUrl or chainName for endpoint resolution, and blockNumOrHash to specify the simulation context (defaults to "latest").

How does the Arbitrum MCP Server resolve RPC endpoints?

The server uses the resolveRpcUrl() function in src/index.ts to determine the final RPC endpoint. It accepts either a direct URL via args.rpcUrl, a chain identifier via args.chainName (resolved through src/services/chain-lookup.ts), or falls back to a default URL configured via the set_rpc_url tool.

Can I use arbtrace_call without setting a default RPC URL?

Yes. While you can configure a default RPC URL using the set_rpc_url tool for convenience, you can also provide the rpcUrl parameter directly in each arbtrace_call request, or specify a chainName that the server resolves to an appropriate endpoint via the chain lookup service in src/services/chain-lookup.ts.

What trace types are supported by arbtrace_call?

The tool supports standard Nitro trace types including "trace" (execution trace), "stateDiff" (state changes), and "vmTrace" (virtual machine trace). You specify these in the traceTypes array parameter, and the Nitro node returns the corresponding trace data in the TraceResult object according to the implementation in src/clients/nitro-node-client.ts.

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