Arbitrum MCP Server Node Operations: Complete Tool Reference

The Arbitrum MCP Server exposes 20+ RPC-based node operations through the NitroNodeClient class, covering health monitoring, block tracing, validation, maintenance, and Timeboost auction management.

The Arbitrum MCP Server (dewanshparashar/arbitrum-mcp) provides Model Context Protocol (MCP) tools that interface directly with Arbitrum Nitro nodes. These operations allow AI agents and applications to query node health, trace transactions, validate state, and manage express-lane auctions through standardized JSON-RPC calls.

Legacy Node Status Operations

The server implements three core diagnostic tools for monitoring node health and connectivity. These map to standard Ethereum and Arbitrum admin APIs.

Node Health Checks

The node_health tool calls arb_getHealth via the admin API to report the current health status of a Nitro node. Implemented in src/clients/nitro-node-client.ts at lines 70-84, the NitroNodeClient.getHealth() method returns the node's operational state.

// Tool: node_health
// Calls NitroNodeClient.getHealth(rpcUrl)
const result = await client.getHealth("https://arb1.arbitrum.io/rpc");

Synchronization Status

The sync_status tool invokes eth_syncing (with a fallback to eth_blockNumber) to determine whether a node is fully synchronized or still catching up with the chain. The NitroNodeClient.getSyncStatus() method at lines 87-133 handles the logic for parsing sync progress or returning the current block height when synced.

Peer Discovery

The node_peers tool exposes admin_peers to list all connected peers. The implementation at src/clients/nitro-node-client.ts lines 136-152 provides network topology data for debugging connectivity issues.

Publisher and Validation Operations

Publisher Health Monitoring

The arb_check_publisher_health tool verifies the health of the transaction publisher (sequencer) through the arb_checkPublisherHealth RPC method. This is implemented in NitroNodeClient.checkPublisherHealth() at lines 56-69.

Raw Block Metadata

For advanced debugging, the arb_get_raw_block_metadata tool fetches uncompressed block metadata for specified block ranges. The NitroNodeClient.getRawBlockMetadata() method (lines 172-188) handles these requests, returning internal Arbitrum-specific block data structures.

Latest Validated State

The arb_latest_validated tool retrieves the most recent validated global state through arb_latestValidated. Implemented at lines 200-210 in NitroNodeClient.getLatestValidated(), this operation is critical for confirming finality in Arbitrum's rollup architecture.

Trace API Operations

The server exposes a comprehensive Trace API with nine distinct tools for transaction tracing and debugging. These methods map to Arbitrum's arbtrace_* namespace.

Single and Batch Call Tracing

• arbtrace_call: Traces a single call with optional trace types (e.g., "trace", "vmTrace", "stateDiff"). Implemented in NitroNodeClient.traceCall() at lines 215-235.
• arbtrace_callMany: Batch-traces multiple calls in a single request. The traceCallMany() method at lines 237-254 accepts an array of call objects and trace configurations.

Block and Transaction Replay

• arbtrace_replayBlockTransactions: Replays and traces all transactions within a specific block. See replayBlockTransactions() at lines 257-275.
• arbtrace_replayTransaction: Replays and traces a single transaction by hash. Implemented in replayTransaction() at lines 277-295.
• arbtrace_transaction: Retrieves trace data for a given transaction hash without full replay. See traceTransaction() at lines 298-313.

Advanced Trace Queries

• arbtrace_get: Retrieves a specific path within an existing trace object. Implemented in traceGet() at lines 311-327.
• arbtrace_block: Traces all transactions in a block, returning structured trace data. See traceBlock() at lines 329-345.
• arbtrace_filter: Filters traces using custom criteria such as address ranges or block numbers. Implemented in traceFilter() at lines 347-363.

Debug and Maintenance Operations

Debug API

The server provides low-level debugging tools for validation:

• arbdebug_validateMessageNumber: Validates a specific L2 message number through NitroNodeClient.validateMessageNumber() (lines 555-575).
• arbdebug_validationInputsAt: Fetches validation inputs for a specific message via getValidationInputsAt() (lines 587-606).

Maintenance API

Node operators can monitor and trigger maintenance tasks:

• maintenance_status: Reports seconds since the last maintenance run by calling maintenance_secondsSinceLastMaintenance. Implemented in getMaintenanceStatus() at lines 512-528.
• maintenance_trigger: Manually initiates a maintenance operation through maintenance_trigger. See triggerMaintenance() at lines 530-548.

Timeboost and Auctioneer Operations

Express Lane Transactions

The timeboost_sendExpressLaneTransaction tool submits priority transactions to Arbitrum's Timeboost express lanes. This calls timeboost_sendExpressLaneTransaction via NitroNodeClient.sendExpressLaneTransaction() at lines 488-506.

Auction Resolution

The auctioneer_submitAuctionResolutionTransaction tool handles auction resolution for express lane rights. Implemented in submitAuctionResolutionTransaction() at lines 512-531, this operation is essential for the Timeboost auction mechanism.

Implementation Architecture

All node operations are registered in the tool registry within src/index.ts (see the "NEW ARBITRUM NODE TOOLS" and "MONITORING TOOLS" sections starting around line 1000). The server instantiates NitroNodeClient with a resolved RPC URL—determined by resolveRpcUrl() (lines 54-88)—and routes incoming MCP tool requests to the appropriate client method.

The request handler in CallToolRequestSchema (around line 540) uses a switch statement to map tool names like arbtrace_call or node_health to their corresponding NitroNodeClient implementations, returning JSON-stringified results to the caller.

Summary

• The Arbitrum MCP Server exposes 20+ node operations categorized into health monitoring, tracing, validation, maintenance, and Timeboost auctions.
• All operations are implemented in src/clients/nitro-node-client.ts within the NitroNodeClient class.
• Tools are registered in src/index.ts and handle RPC URL resolution through resolveRpcUrl().
• The Trace API provides the most extensive coverage with nine distinct tracing methods for debugging transactions and blocks.
• Timeboost operations enable interaction with Arbitrum's priority transaction lanes and auction mechanisms.

Frequently Asked Questions

How do I check if an Arbitrum node is fully synchronized using the MCP server?

Call the sync_status tool, which invokes eth_syncing through NitroNodeClient.getSyncStatus(). If the node is synced, it returns the current block number; if syncing, it returns progress data including current, highest, and starting block heights.

What is the difference between arbtrace_call and arbtrace_transaction?

arbtrace_call simulates a call against the current state without requiring a transaction hash, useful for testing hypothetical transactions. arbtrace_transaction retrieves the trace of an already-mined transaction by its hash. The former uses traceCall() while the latter uses traceTransaction() in src/clients/nitro-node-client.ts.

Which node operations require admin API access?

Operations like node_health (calling arb_getHealth) and node_peers (calling admin_peers) require the RPC endpoint to have admin APIs enabled. Standard tracing and block query operations typically work with standard RPC endpoints, though some debug methods may require additional permissions.

Can the MCP server submit transactions to Arbitrum's express lanes?

Yes. The timeboost_sendExpressLaneTransaction tool allows submission of priority transactions to Timeboost express lanes through the sendExpressLaneTransaction() method, while auctioneer_submitAuctionResolutionTransaction handles auction settlements for lane rights.

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