How to Query Arbitrum Nitro Node Health Using the MCP Server

The MCP server exposes a node_health tool that internally invokes NitroNodeClient.getHealth() to execute the arb_getHealth RPC method, returning node status and health metrics from any Arbitrum Nitro endpoint.

The dewanshparashar/arbitrum-mcp repository provides a Model-Context-Protocol (MCP) server implementation that standardizes interactions with Arbitrum Nitro nodes. Through the node_health tool, developers can programmatically assess node viability without managing low-level RPC connections manually.

Understanding the node_health Tool Architecture

The health checking capability is registered as a standard MCP tool within the server's initialization sequence.

Tool Registration in src/index.ts

In src/index.ts (lines 154-168), the server instantiates the Server class and registers the node_health tool alongside other utilities. When the MCP client sends a CallToolRequest, the server routes the invocation to the appropriate handler, which constructs a NitroNodeClient instance and prepares the RPC call.

RPC Endpoint Resolution Strategies

The tool accepts two mutually exclusive parameters for specifying the target node:

• rpcUrl: A direct HTTP(S) endpoint to an Arbitrum Nitro node
• chainName: A human-readable identifier (e.g., "Arbitrum One") that the server resolves via ChainLookupService defined in src/services/chain-lookup.ts

If neither parameter is provided, the tool utilizes a default RPC URL previously configured via the set_rpc_url tool.

Executing Health Queries

The getHealth() Implementation

The actual health check logic resides in src/clients/nitro-node-client.ts. The getHealth() method (lines 70-84) constructs a JSON-RPC payload calling the arb_getHealth admin method.

When the node exposes the admin API, the method returns an object containing:

• status: Current health state of the node
• lastUpdated: Timestamp of the last health check

If the endpoint does not support the admin API or the method is unavailable, the implementation returns a structured "unavailable" response with an explanatory error message rather than throwing an unhandled exception.

Invocation Patterns

You can query node health through three distinct patterns depending on your configuration needs.

Code Examples for Querying Node Health

Setting a Default RPC Endpoint

Configure a persistent default URL to simplify subsequent calls:

await server.callTool({
  name: "set_rpc_url",
  arguments: { 
    rpcUrl: "https://arb1.arbitrum.io/rpc" 
  },
});

Querying Using Chain Names

Leverage the built-in ChainLookupService to resolve known networks:

const health = await server.callTool({
  name: "node_health",
  arguments: { 
    chainName: "Arbitrum One" 
  },
});
console.log("Health status:", health.content[0].text);

Querying Custom RPC Endpoints

Pass a specific URL directly for private or development nodes:

const health = await server.callTool({
  name: "node_health",
  arguments: { 
    rpcUrl: "https://my-custom-node.example/rpc" 
  },
});
console.log("Custom node health:", health.content[0].text);

Querying with Default Configuration

Once set_rpc_url has been called, invoke node_health without arguments:

const health = await server.callTool({
  name: "node_health",
  arguments: {},
});
console.log("Node health:", health.content[0].text);

Error Handling and Fallback Behavior

According to the source code in src/clients/nitro-node-client.ts, the health check implements graceful degradation. If the target node does not expose the arb_getHealth admin endpoint—common for public RPC providers—the client returns a structured unavailable status rather than a connection error. This ensures that MCP clients receive predictable JSON responses regardless of node configuration.

Summary

• The node_health tool in dewanshparashar/arbitrum-mcp provides standardized access to Arbitrum Nitro health metrics via the arb_getHealth RPC method.
• The server accepts either rpcUrl for direct endpoints or chainName for resolved networks through ChainLookupService.
• NitroNodeClient.getHealth() handles the underlying JSON-RPC call and implements fallback logic for nodes without admin API access.
• Configure persistent endpoints using set_rpc_url to streamline repeated health queries without passing URL parameters.

Frequently Asked Questions

What RPC method does the MCP server use to check Arbitrum Nitro health?

The server calls the arb_getHealth JSON-RPC method through NitroNodeClient.getHealth() implemented in src/clients/nitro-node-client.ts. This admin method returns the current operational status and last update timestamp of the Nitro node.

Can I query node health without specifying an RPC URL every time?

Yes. First invoke the set_rpc_url tool with your endpoint, then call node_health with empty arguments. The server stores the default URL and applies it to subsequent health checks automatically.

What happens if the Arbitrum node doesn't support the health check endpoint?

If the node does not expose the admin API or arb_getHealth is disabled, the client returns a structured "unavailable" response with an explanatory error message. This behavior is defined in lines 70-84 of src/clients/nitro-node-client.ts and prevents connection exceptions from propagating to the MCP client.

How does the server resolve chain names like "Arbitrum One"?

The ChainLookupService in src/services/chain-lookup.ts maps human-readable chain names to their canonical RPC URLs. When you provide the chainName argument to node_health, the service resolves it to a URL before NitroNodeClient executes the health check.

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