# How to Get the ArbOS Version for a Specific Arbitrum Chain Using the MCP Server

> Learn how to get Arbos version for any Arbitrum chain using the MCP server. This guide explains how to use the arbos_version tool with chain names or RPC URLs for quick results.

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

---

**To retrieve the ArbOS version for any Arbitrum chain using the arbitrum-mcp server, invoke the `arbos_version` tool with either a chain name (e.g., "Arbitrum One") or a direct RPC URL, and the server will return the version string via the `ArbitrumChainClient.getArbOSVersion()` method.**

The `dewanshparashar/arbitrum-mcp` repository provides a Model Context Protocol (MCP) server that exposes Arbitrum-specific tooling to AI agents and applications. Checking the ArbOS version is essential for compatibility verification, debugging, and ensuring that your integration targets the correct state of the Arbitrum protocol.

## Understanding the ArbOS Version Retrieval Flow

When you request the ArbOS version through the MCP server, the system executes a four-step resolution process:

1. **RPC Endpoint Resolution** – If you provide a **chain name** (such as `Arbitrum One`, `Nova`, or `Xai`), the server uses the `ChainLookupService` to resolve the corresponding RPC URL. You may also bypass this step by providing the RPC URL directly.

2. **Client Initialization** – The server instantiates an `ArbitrumChainClient` using the resolved RPC endpoint.

3. **Version Query** – The client calls `getArbOSVersion()`, which first attempts to use the Orbit SDK utility. If the node does not support that specific call, it automatically falls back to a standard JSON-RPC request using the `arb_getVersion` method.

4. **Response Formatting** – The version string is wrapped in a tool response and returned to the caller.

## Prerequisites and Setup

To use the ArbOS version tool, you must have the arbitrum-mcp server running and accessible to your MCP client. The server is typically started via Node.js:

```bash
node src/index.ts

```

Ensure your MCP client (such as Claude Desktop or a custom implementation) is configured to connect to this server endpoint.

## How to Get the ArbOS Version Using the MCP Tool

The `arbos_version` tool accepts either a chain name for automatic lookup or a direct RPC URL. You may also configure a default RPC URL to avoid repetition.

### Method 1: Using a Chain Name (Automatic RPC Resolution)

Pass the `chainName` argument to let the server resolve the RPC endpoint automatically. This uses the internal chain registry to find the correct URL.

```json
{
  "name": "arbos_version",
  "arguments": {
    "chainName": "Arbitrum One"
  }
}

```

**Example response:**

```

ArbOS Version: 2.0.3

```

### Method 2: Using a Direct RPC URL

If you know the specific RPC endpoint, pass it directly via the `rpcUrl` argument. This bypasses the chain lookup service entirely.

```json
{
  "name": "arbos_version",
  "arguments": {
    "rpcUrl": "https://arb1.arbitrum.io/rpc"
  }
}

```

### Method 3: Using a Default RPC Configuration

First, set a default RPC URL using the `set_rpc_url` tool. Subsequent calls to `arbos_version` can then omit the arguments, using the stored default.

```json
// Set the default RPC URL
{
  "name": "set_rpc_url",
  "arguments": {
    "rpcUrl": "https://arb1.arbitrum.io/rpc"
  }
}

```

```json
// Retrieve version using the default
{
  "name": "arbos_version",
  "arguments": {}
}

```

> **Note:** If the target node does not support ArbOS version queries, the tool returns a fallback message such as `"Unknown (RPC does not support ArbOS version queries)"` rather than throwing an error.

## Implementation Details: How the Server Retrieves ArbOS Versions

The arbitrum-mcp server implements the version retrieval across three core components. Understanding these internals helps debug issues or extend functionality.

### Tool Registration and RPC Resolution ([`src/index.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/index.ts))

The main entry point registers the `arbos_version` tool and handles incoming requests. The `resolveRpcUrl` helper (lines 54-71) determines whether to use a provided URL or look up a chain name:

```typescript
// src/index.ts lines 54-71
async function resolveRpcUrl(args: any): Promise<string> {
  if (args.rpcUrl) {
    return args.rpcUrl;
  }
  if (args.chainName) {
    const chain = await chainLookupService.findChainByName(args.chainName);
    if (!chain) {
      throw new Error(`Chain not found: ${args.chainName}`);
    }
    return chain.rpcUrl;
  }
  throw new Error('Either rpcUrl or chainName must be provided');
}

```

The tool handler itself (lines 108-127) instantiates the client and returns the version:

```typescript
// src/index.ts lines 108-127
case 'arbos_version': {
  const rpcUrl = await resolveRpcUrl(args);
  const client = new ArbitrumChainClient(rpcUrl);
  const version = await client.getArbOSVersion();
  return {
    content: [{
      type: 'text',
      text: `ArbOS Version: ${version}`
    }]
  };
}

```

### Chain Lookup Service ([`src/services/chain-lookup.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/services/chain-lookup.ts))

The `ChainLookupService` maintains an internal registry of Arbitrum chains. The `findChainByName` method (lines 64-73) performs case-insensitive matching against known chains like "Arbitrum One", "Nova", or "Xai":

```typescript
// src/services/chain-lookup.ts lines 64-73
async findChainByName(name: string): Promise<ChainInfo | undefined> {
  const chains = await this.getChains();
  return chains.find(chain => 
    chain.name.toLowerCase() === name.toLowerCase() ||
    chain.chainId.toString() === name
  );
}

```

### ArbOS Version Query Logic ([`src/clients/arbitrum-chain-client.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/arbitrum-chain-client.ts))

The `ArbitrumChainClient` class encapsulates the blockchain interaction. The `getArbOSVersion` method (lines 46-61) implements a dual-strategy approach:

```typescript
// src/clients/arbitrum-chain-client.ts lines 46-61
async getArbOSVersion(): Promise<string> {
  try {
    // Primary: Use Orbit SDK utility
    const version = await getArbOSVersion(this.rpcUrl);
    return version;
  } catch (error) {
    // Fallback: Direct JSON-RPC call
    const response = await this.provider.send('arb_getVersion', []);
    if (response && response.version) {
      return response.version;
    }
    return 'Unknown (RPC does not support ArbOS version queries)';
  }
}

```

This implementation ensures compatibility across different Arbitrum node configurations, including Orbit chains that may not expose the standard SDK methods.

## Summary

- **Use the `arbos_version` tool** in the arbitrum-mcp server to retrieve ArbOS versions for any Arbitrum chain.
- **Provide either a `chainName`** (e.g., "Arbitrum One", "Nova") for automatic RPC resolution via `ChainLookupService`, or a **`rpcUrl`** for direct access.
- **The server handles compatibility** by first attempting the Orbit SDK method, then falling back to the `arb_getVersion` JSON-RPC call if needed.
- **Key implementation files** include [`src/index.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/index.ts) for tool registration, [`src/services/chain-lookup.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/services/chain-lookup.ts) for chain resolution, and [`src/clients/arbitrum-chain-client.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/arbitrum-chain-client.ts) for the version query logic.

## Frequently Asked Questions

### What is ArbOS and why do I need to check its version?

ArbOS is the Layer 2 operating system that runs on Arbitrum chains, managing the execution environment and state transitions. Checking the ArbOS version is essential for ensuring compatibility with specific features, debugging transaction behavior, and verifying that your integration targets the correct protocol state. Different versions may support different precompiles or behave differently during edge cases.

### Can I retrieve the ArbOS version without knowing the RPC URL?

Yes. The arbitrum-mcp server includes a `ChainLookupService` that maintains a registry of known Arbitrum chains. By passing the `chainName` argument (such as "Arbitrum One", "Nova", or "Xai") to the `arbos_version` tool, the server automatically resolves the appropriate RPC URL internally, eliminating the need to manually configure endpoints for well-known chains.

### What happens if the Arbitrum node doesn't support ArbOS version queries?

The `ArbitrumChainClient.getArbOSVersion()` method implements a graceful fallback strategy. It first attempts to retrieve the version using the Orbit SDK utility. If that fails, it automatically falls back to a direct JSON-RPC call to `arb_getVersion`. If neither method succeeds, the tool returns the string `"Unknown (RPC does not support ArbOS version queries)"` rather than throwing an exception, ensuring your application remains stable.

### Is the arbitrum-mcp server compatible with all Arbitrum chains?

The server is designed to work with any Arbitrum-compatible chain, including Arbitrum One, Nova, and custom Orbit chains. For well-known chains, the built-in `ChainLookupService` provides automatic RPC resolution. For custom or private chains, you can bypass the lookup service by providing the `rpcUrl` argument directly. The version detection logic in `ArbitrumChainClient` adapts to different node configurations, making the tool universally applicable across the Arbitrum ecosystem.