How to Get the Sync Status of an Arbitrum Nitro Node with the MCP Server

You can retrieve the sync status of an Arbitrum Nitro node by invoking the sync_status tool on the arbitrum-mcp server, which internally queries eth_syncing and eth_blockNumber via the NitroNodeClient class.

The dewanshparashar/arbitrum-mcp repository implements a Model Context Protocol (MCP) server that exposes JSON-RPC tools for interacting with Arbitrum Nitro nodes. Checking whether a node has fully synchronized with the network or is still catching up is a critical operational task, and the server provides a dedicated tool for this purpose.

Understanding the sync_status Tool Implementation

The sync_status tool is registered in src/index.ts and delegates its work to the NitroNodeClient class. Understanding this flow helps diagnose connection issues and interpret response data correctly.

RPC Endpoint Resolution via ChainLookupService

When you invoke the tool, the server first resolves the target RPC endpoint. In src/index.ts (lines 70-88), the handler checks whether you provided an explicit rpcUrl parameter. If omitted, it uses the ChainLookupService to map a chain name (such as "arb1") to a known public RPC URL. This resolution happens before any node communication begins.

The NitroNodeClient.getSyncStatus() Method

Once the endpoint is resolved, the server instantiates NitroNodeClient in src/index.ts (lines 149-155) and calls getSyncStatus(). The core logic resides in src/clients/nitro-node-client.ts (lines 87-133).

This method performs two sequential JSON-RPC calls:

1. eth_syncing – Returns an object with currentBlock, highestBlock, and other sync metadata if the node is actively synchronizing. If the node is fully synced, this returns false.
2. eth_blockNumber – Acts as a fallback when eth_syncing returns false or fails. This retrieves the current canonical block number to confirm the node is at the chain head.

The method then calculates a syncProgress percentage and returns a structured object containing currentBlock, highestBlock, isSyncing, syncProgress, and an optional error field.

Methods to Check Arbitrum Nitro Node Sync Status

You can interact with the sync_status tool through three primary interfaces: the provided CLI binary, direct JSON-RPC requests, or programmatic HTTP clients.

Using the CLI Binary

The arbitrum-mcp CLI provides the simplest interface for one-off checks. First, optionally set a default RPC URL to avoid passing it with every command:

arbitrum-mcp call set_rpc_url '{"rpcUrl":"https://arb1.arbitrum.io/rpc"}'

Then query the sync status:

arbitrum-mcp call sync_status '{}'

If you skip the set_rpc_url step, provide the URL directly:

arbitrum-mcp call sync_status '{"rpcUrl":"https://arb1.arbitrum.io/rpc"}'

Sending a Direct JSON-RPC Request to the MCP Server

When running the MCP server as an HTTP service (typically on port 8080), you can send standard MCP protocol requests. The payload structure follows the Model Context Protocol specification:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "call_tool",
  "params": {
    "name": "sync_status",
    "arguments": {
      "rpcUrl": "https://arb1.arbitrum.io/rpc"
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"currentBlock\": 12345678,\n  \"highestBlock\": 12345900,\n  \"isSyncing\": true,\n  \"syncProgress\": 97.6\n}"
      }
    ]
  }
}

Programmatic Access with TypeScript or JavaScript

For integration into existing applications, use a standard HTTP client like node-fetch or axios to communicate with the MCP server:

import fetch from "node-fetch";

const payload = {
  jsonrpc: "2.0",
  id: 1,
  method: "call_tool",
  params: {
    name: "sync_status",
    arguments: { rpcUrl: "https://arb1.arbitrum.io/rpc" },
  },
};

const res = await fetch("http://localhost:8080", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

const { result } = await res.json();
const syncData = JSON.parse(result.content[0].text);

console.log(`Sync Progress: ${syncData.syncProgress}%`);
console.log(`Currently Syncing: ${syncData.isSyncing}`);

Interpreting the Sync Status Response

The sync_status tool returns a JSON object with the following fields:

• currentBlock – The block number the node has currently processed.
• highestBlock – The target block number the node is syncing toward (only present when isSyncing is true).
• isSyncing – Boolean indicating whether the node is actively synchronizing.
• syncProgress – Float representing the percentage of completion (0–100).
• error – Optional string containing error details if the RPC call fails.

When isSyncing is false and no error is present, the node is fully synchronized with the Arbitrum network head.

Summary

• The arbitrum-mcp server exposes a sync_status tool in src/index.ts that queries Arbitrum Nitro nodes via JSON-RPC.
• Endpoint resolution uses either an explicit rpcUrl parameter or the ChainLookupService to map chain names to URLs.
• Core logic resides in src/clients/nitro-node-client.ts, where getSyncStatus() calls eth_syncing and falls back to eth_blockNumber.
• You can invoke the tool via the CLI (arbitrum-mcp call sync_status), direct JSON-RPC to the MCP server, or programmatic HTTP clients.
• The response includes currentBlock, highestBlock, isSyncing, syncProgress, and optional error fields.

Frequently Asked Questions

What RPC methods does the sync_status tool use internally?

The sync_status tool uses two standard Ethereum JSON-RPC methods. First, it calls eth_syncing to retrieve sync metadata including currentBlock and highestBlock. If this call returns false (indicating the node is synced) or fails entirely, the tool falls back to eth_blockNumber to confirm the current canonical block height. This dual-method approach ensures accurate status reporting regardless of the node's synchronization state.

Can I use a chain name instead of a full RPC URL?

Yes. If you omit the rpcUrl parameter when calling sync_status, the MCP server uses the ChainLookupService (defined in src/services/chain-lookup.ts) to resolve common chain identifiers like "arb1" or "nova" to their canonical public RPC endpoints. This abstraction simplifies CLI usage and reduces configuration overhead when monitoring well-known Arbitrum networks.

What does it mean when isSyncing is false in the response?

When the isSyncing field returns false, the Arbitrum Nitro node has fully synchronized with the network head. In this state, the highestBlock field is typically omitted, and currentBlock represents the latest canonical block known to the node. The syncProgress field will show 100%, indicating no further catch-up is required. This status confirms the node is ready to serve live traffic and respond to current state queries.

How do I handle RPC connection errors when querying sync status?

The sync_status tool includes robust error handling within src/clients/nitro-node-client.ts. If the RPC endpoint is unreachable or returns malformed data, the tool populates the optional error field in the JSON response with a descriptive message while still returning a valid MCP result structure. When building automation around this tool, always check for the presence of the error field before trusting the syncProgress or isSyncing values, and implement retry logic with exponential backoff for transient network failures.

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