Arbitrum MCP Server

Instructions

Implementation Reference

• src/index.ts:579-595 (handler)

  MCP server handler for the 'arbtrace_block' tool. Resolves the RPC URL from chainName or rpcUrl, instantiates NitroNodeClient, calls its traceBlock method with the provided blockNumOrHash, and returns the JSON-stringified result.
  case "arbtrace_block": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.traceBlock( args.blockNumOrHash as string ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; }
• src/index.ts:1353-1375 (schema)

  Tool schema definition including name, description, and inputSchema for 'arbtrace_block' in the getAvailableTools() method.
  name: "arbtrace_block", description: "Get trace information for all transactions in a block (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, blockNumOrHash: { type: "string", description: "Block number or hash to trace", }, }, required: ["blockNumOrHash"], },
• src/index.ts:821-1681 (registration)

  Registration of all MCP tools including 'arbtrace_block' via the getAvailableTools() method called by ListToolsRequestSchema handler.
  private getAvailableTools(): Tool[] { console.error("ArbitrumMCPServer: Creating tools list"); const tools = [ { name: "set_rpc_url", description: "Set the default RPC URL for subsequent requests", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL to set as default", }, }, required: ["rpcUrl"], }, }, { name: "get_rpc_url", description: "Get the current default RPC URL", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "clear_rpc_url", description: "Clear the default RPC URL", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "node_health", description: "Check Arbitrum node health status (requires admin API access - may not work with public RPCs)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, }, required: [], }, }, { name: "sync_status", description: "Get node synchronization status (may fall back to current block number if sync API unavailable)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, }, required: [], }, }, { name: "node_peers", description: "Get connected peers information (requires admin API access - will not work with public RPCs)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, }, required: [], }, }, { name: "arbos_version", description: "Get the ArbOS version number for any Arbitrum chain. Use this for questions like 'what ArbOS version is Xai running?', 'ArbOS version of Arbitrum One', 'what version of ArbOS', or 'check ArbOS version'. Supports chain names like 'Xai', 'Arbitrum One', 'Nova', etc.", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One', 'Nova') - will auto-resolve to RPC URL", }, }, required: [], }, }, { name: "latest_block", description: "Get the latest block information", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the chain (optional if default is set)", }, }, required: [], }, }, { name: "get_balance", description: "Get balance of an address in wei", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the chain (optional if default is set)", }, address: { type: "string", description: "Ethereum address to check balance for", }, }, required: ["address"], }, }, { name: "get_balance_ether", description: "Get balance of an address in ETH", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the chain (optional if default is set)", }, address: { type: "string", description: "Ethereum address to check balance for", }, }, required: ["address"], }, }, { name: "get_transaction", description: "Get transaction details by hash", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the chain (optional if default is set)", }, txHash: { type: "string", description: "Transaction hash", }, }, required: ["txHash"], }, }, { name: "get_transaction_receipt", description: "Get transaction receipt by hash", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the chain (optional if default is set)", }, txHash: { type: "string", description: "Transaction hash", }, }, required: ["txHash"], }, }, { name: "is_contract", description: "Check if an address is a contract", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the chain (optional if default is set)", }, address: { type: "string", description: "Address to check", }, }, required: ["address"], }, }, { name: "list_chains", description: "List all available Arbitrum Orbit chains and their names. Use this to see what chains are available for querying.", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "search_chains", description: "Search for Arbitrum chains by name, chain ID, or partial name match. Perfect for finding chains when you have incomplete information.", inputSchema: { type: "object" as const, properties: { query: { type: "string", description: "Search query (chain name like 'Xai', 'Arbitrum One', chain ID like '42161', or partial name)", }, }, required: ["query"], }, }, { name: "chain_info", description: "Get comprehensive chain information including rollup contract address, bridge addresses, chain ID, RPC URL, explorer URL, native token details, and all bridge contract addresses. Use this for questions about rollup addresses, bridge contracts, chain IDs, or any chain-specific data for Arbitrum chains like Xai, Arbitrum One, etc.", inputSchema: { type: "object" as const, properties: { chainName: { type: "string", description: "Chain name to look up (e.g., 'Xai', 'Arbitrum One', 'Nova', 'Stylus')", }, }, required: ["chainName"], }, }, { name: "get_rollup_address", description: "Get the rollup contract address for a specific Arbitrum chain. Use this for direct rollup address queries like 'what's the rollup address of Xai?', 'Xai rollup contract', or 'rollup address for Arbitrum One'.", inputSchema: { type: "object" as const, properties: { chainName: { type: "string", description: "Chain name to get rollup address for (e.g., 'Xai', 'Arbitrum One', 'Nova')", }, }, required: ["chainName"], }, }, // ========== NEW ARBITRUM NODE TOOLS ========== { name: "arb_check_publisher_health", description: "Check the health status of the transaction publisher/sequencer (requires admin API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, }, required: [], }, }, { name: "arb_get_raw_block_metadata", description: "Retrieve raw block metadata for specified block ranges (requires admin API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, fromBlock: { type: "number", description: "Starting block number", }, toBlock: { type: "number", description: "Ending block number (defaults to fromBlock if not provided)", }, }, required: ["fromBlock"], }, }, { name: "arb_latest_validated", description: "Get the latest validated global state information (requires admin API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, }, required: [], }, }, { name: "arbtrace_call", description: "Trace individual calls with specified trace types (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, callArgs: { type: "object", description: "Call arguments (to, from, data, etc.)", }, traceTypes: { type: "array", description: "Array of trace types (e.g., ['trace', 'stateDiff'])", items: { type: "string" }, }, blockNumOrHash: { type: "string", description: "Block number or hash (defaults to 'latest')", }, }, required: ["callArgs"], }, }, { name: "arbtrace_callMany", description: "Trace multiple calls in batch for efficiency (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, calls: { type: "array", description: "Array of call objects to trace", items: { type: "object" }, }, blockNumOrHash: { type: "string", description: "Block number or hash (defaults to 'latest')", }, }, required: ["calls"], }, }, { name: "arbtrace_replayBlockTransactions", description: "Replay and trace all transactions in a specific block (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, blockNumOrHash: { type: "string", description: "Block number or hash to replay", }, traceTypes: { type: "array", description: "Array of trace types (e.g., ['trace', 'stateDiff'])", items: { type: "string" }, }, }, required: ["blockNumOrHash"], }, }, { name: "arbtrace_replayTransaction", description: "Replay and trace a specific transaction (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, txHash: { type: "string", description: "Transaction hash to replay", }, traceTypes: { type: "array", description: "Array of trace types (e.g., ['trace', 'stateDiff'])", items: { type: "string" }, }, }, required: ["txHash"], }, }, { name: "arbtrace_transaction", description: "Get trace information for a specific transaction (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, txHash: { type: "string", description: "Transaction hash to trace", }, }, required: ["txHash"], }, }, { name: "arbtrace_get", description: "Get specific trace data at a given path within a transaction (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, txHash: { type: "string", description: "Transaction hash", }, path: { type: "array", description: "Path to specific trace data", items: { type: "string" }, }, }, required: ["txHash"], }, }, { name: "arbtrace_block", description: "Get trace information for all transactions in a block (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, blockNumOrHash: { type: "string", description: "Block number or hash to trace", }, }, required: ["blockNumOrHash"], }, }, { name: "arbtrace_filter", description: "Filter traces based on specified criteria (requires trace API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, filter: { type: "object", description: "Filter criteria for traces", }, }, required: ["filter"], }, }, { name: "arbdebug_validateMessageNumber", description: "Validate a specific message number (requires debug API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, msgNum: { type: "number", description: "Message number to validate", }, full: { type: "boolean", description: "Whether to perform full validation", }, moduleRoot: { type: "string", description: "Optional module root hash", }, }, required: ["msgNum"], }, }, { name: "arbdebug_validationInputsAt", description: "Get validation inputs at a specific message (requires debug API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, msgNum: { type: "number", description: "Message number to get validation inputs for", }, target: { type: "string", description: "Target for validation inputs", }, }, required: ["msgNum"], }, }, { name: "maintenance_status", description: "Check maintenance status - seconds since last maintenance (requires admin API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, }, required: [], }, }, { name: "maintenance_trigger", description: "Manually trigger maintenance operations (requires admin API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, }, required: [], }, }, { name: "timeboost_sendExpressLaneTransaction", description: "Submit priority transactions through express lanes for faster processing (requires timeboost API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, submission: { type: "object", description: "Express lane submission data", }, }, required: ["submission"], }, }, { name: "auctioneer_submitAuctionResolutionTransaction", description: "Submit auction resolution transactions for express lane functionality (requires auctioneer API)", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum node (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, transaction: { type: "object", description: "Auction resolution transaction data", }, }, required: ["transaction"], }, }, // ========== MONITORING TOOLS ========== { name: "batch_posting_status", description: "Monitor batch posting activity. Tracks when batches were last posted to the sequencer inbox and current backlog size. Essential for PM and support teams to understand chain data availability status.", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum chain (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, parentRpcUrl: { type: "string", description: "Parent chain RPC URL (e.g., Ethereum mainnet RPC)", }, sequencerInboxAddress: { type: "string", description: "Sequencer inbox contract address", }, bridgeAddress: { type: "string", description: "Bridge contract address", }, }, required: ["parentRpcUrl", "sequencerInboxAddress", "bridgeAddress"], }, }, { name: "assertion_status", description: "Monitor assertion creation and confirmation activity. Tracks NodeCreated vs NodeConfirmed events to understand rollup validation status. Critical for PM and support teams to monitor chain security and finality.", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum chain (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, parentRpcUrl: { type: "string", description: "Parent chain RPC URL (e.g., Ethereum mainnet RPC)", }, rollupAddress: { type: "string", description: "Rollup contract address", }, }, required: ["parentRpcUrl", "rollupAddress"], }, }, { name: "gas_status", description: "Monitor current gas prices on the chain. Essential for identifying gas price spikes and understanding transaction costs. Useful for PM and support teams to monitor network congestion.", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum chain (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL", }, }, required: [], }, }, { name: "comprehensive_chain_status", description: "Get comprehensive chain status including ArbOS version, batch posting, assertion monitoring, and gas prices. Perfect for PM and support teams asking 'what is the current status of XAI?' or similar comprehensive status checks. Auto-resolves contract addresses from chain name when possible.", inputSchema: { type: "object" as const, properties: { rpcUrl: { type: "string", description: "The RPC URL of the Arbitrum chain (optional if default is set)", }, chainName: { type: "string", description: "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve RPC URL and contract addresses", }, parentRpcUrl: { type: "string", description: "Parent chain RPC URL (auto-resolved if chainName provided)", }, sequencerInboxAddress: { type: "string", description: "Sequencer inbox contract address (auto-resolved if chainName provided)", }, bridgeAddress: { type: "string", description: "Bridge contract address (auto-resolved if chainName provided)", }, rollupAddress: { type: "string", description: "Rollup contract address (auto-resolved if chainName provided)", }, }, required: [], }, }, ]; console.error(`ArbitrumMCPServer: Created ${tools.length} tools`); return tools; }
• src/clients/nitro-node-client.ts:325-337 (helper)

  NitroNodeClient.traceBlock() helper method that executes the underlying RPC call to 'arbtrace_block' with the block number or hash parameter.
  async traceBlock(blockNumOrHash: string): Promise<TraceResult> { try { const traces = await this.makeRpcCall("arbtrace_block", [blockNumOrHash]); return { traces }; } catch (error) { return { traces: null, error: `Trace block not supported on this RPC endpoint: ${ (error as Error).message }`, }; } }