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

> Learn how to get the sync status of your Arbitrum Nitro node using the arbitrum-mcp server. Discover how to query eth_syncing and eth_blockNumber.

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

---

**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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/index.ts) (lines 149-155) and calls `getSyncStatus()`. The core logic resides in [`src/clients/nitro-node-client.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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:

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

```

Then query the sync status:

```bash
arbitrum-mcp call sync_status '{}'

```

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

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

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

```

**Example Response:**

```json
{
  "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:

```typescript
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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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.