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

> Learn to use arbtrace_call with the Arbitrum MCP Server. Simulate transactions and get detailed traces from Nitro nodes via NitroNodeClient.traceCall().

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

---

**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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/services/chain-lookup.ts)), or falling back to a default URL configured via the `set_rpc_url` tool.

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

```

**`NitroNodeClient.traceCall()`**

Located in [`src/clients/nitro-node-client.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/nitro-node-client.ts), this method constructs the RPC call:

```typescript
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:

```typescript
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:

```typescript
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:

```bash

# 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:

```json
{
  "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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/index.ts) | Request handler mapping `arbtrace_call` to client methods | Lines 65-82 |
| [`src/clients/nitro-node-client.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/nitro-node-client.ts) | `traceCall()` implementation forwarding to Nitro RPC | Lines 15-27 |
| [`src/services/chain-lookup.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/services/chain-lookup.ts) | Resolves chain names to RPC URLs | Full file |
| [`README.md`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/README.md) | General server documentation | Repository root |

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