How to Check the Gas Status of an Arbitrum Chain Using the MCP Server

The gas_status tool in the arbitrum-mcp server returns real-time gas prices for any Arbitrum-compatible chain by accepting either an rpcUrl or chainName parameter and returning the current price in both wei and gwei.

The dewanshparashar/arbitrum-mcp repository provides a Model-Context-Protocol (MCP) server that exposes chain-level Arbitrum data through standardized tools. To check the gas status of an Arbitrum chain using the MCP Server, you invoke the gas_status tool with your preferred chain identifier, and the server handles RPC resolution, on-chain queries, and response formatting automatically.

Understanding the gas_status Tool Implementation

The gas_status tool is registered in src/index.ts (lines 59-70) where it defines the tool schema and binds it to the handler that instantiates ArbitrumChainClient. According to the source code, this tool accepts either a complete rpcUrl string or a human-readable chainName like "Arbitrum One" or "Xai".

When invoked, the server processes the request through a four-stage pipeline that abstracts away direct RPC complexity while returning precise gas metrics.

How the Gas Status Query Works Under the Hood

Tool Registration and Parameter Handling

In src/index.ts, the tool definition specifies the input schema and wires the execution handler to ArbitrumMCPServer. The handler first calls resolveRpcUrl() to normalize the input parameter. If you provide a full URL, the server uses it directly; otherwise, it queries the internal ChainLookupService (implemented in src/services/chain-lookup.ts) to map known chain names to their default RPC endpoints.

Chain Client Initialization and RPC Execution

With the resolved endpoint, the handler creates a new ArbitrumChainClient instance via new ArbitrumChainClient(rpcUrl). This client encapsulates the Viem-based connection logic required to communicate with Arbitrum chains.

Gas Price Retrieval and Formatting

The actual gas fetch occurs in src/clients/arbitrum-chain-client.ts (lines 47-66) within the getGasStatus() method. This function calls publicClient.getGasPrice() to retrieve the current price in wei, converts the value to gwei for readability, and constructs a summary string. If the RPC call fails, the method returns a default error payload with zeroed values and an informative error message rather than throwing.

The method returns a GasStatus object containing:

• currentGasPrice: The raw wei value as a string
• currentGasPriceGwei: The decimal gwei representation
• summary: A human-readable string combining both values

Practical Code Examples

Querying via the MCP SDK (Node.js)

import { Client } from "@modelcontextprotocol/sdk/client";

async function checkGas(chainNameOrRpc: string) {
  const client = new Client({ serverUrl: "http://localhost:8080" });

  const response = await client.callTool({
    name: "gas_status",
    arguments: {
      chainName: chainNameOrRpc,
    },
  });

  console.log("Gas status:", JSON.parse(response.content[0].text));
}

// Example using a known chain name
checkGas("Arbitrum One");

// Example using a custom RPC endpoint
// checkGas("https://arb1.arbitrum.io/rpc");

Direct HTTP Request with cURL

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"call_tool",
    "params":{
      "name":"gas_status",
      "arguments":{"chainName":"Xai"}
    }
  }'

The response contains the JSON-encoded GasStatus object in result.content[0].text.

Command-Line Interface Usage

# Optional: Set a default RPC URL

node ./dist/index.js set_rpc_url --rpcUrl https://arb1.arbitrum.io/rpc

# Query using the default or pass specific arguments

node ./dist/index.js gas_status

Response Format and Error Handling

A successful call returns the following JSON structure:

{
  "currentGasPrice": "123456789012345678",
  "currentGasPriceGwei": "123.45",
  "summary": "Current gas price: 123.45 gwei (123456789012345678 wei)"
}

If the underlying RPC node is unreachable, ArbitrumChainClient.getGasStatus() returns zeroed values with an error description in the summary field, allowing your application to handle gas monitoring failures gracefully without crashing.

Summary

• The gas_status tool in dewanshparashar/arbitrum-mcp provides real-time Arbitrum gas prices through a standardized MCP interface.
• Source locations: Tool registration occurs in src/index.ts (lines 59-70), while the core logic resides in src/clients/arbitrum-chain-client.ts (lines 47-66).
• Input flexibility: Accepts either explicit rpcUrl values or human-readable chainName strings resolved via ChainLookupService.
• Dual-format output: Returns gas prices in both wei (for precise calculations) and gwei (for human readability).
• Error resilience: Failed RPC calls return structured error objects rather than exceptions, ensuring predictable client behavior.

Frequently Asked Questions

What parameters does the gas_status tool accept?

The tool accepts either rpcUrl (a complete JSON-RPC endpoint URL) or chainName (a supported chain identifier like "Arbitrum One"). You do not need to provide both; the server uses resolveRpcUrl() to determine the endpoint from whichever parameter you supply.

How does the MCP server handle unknown chain names?

If you provide a chainName that is not recognized by the internal ChainLookupService, the resolution step fails before reaching the RPC client. You must either use a supported chain name from the server's registry or provide a direct rpcUrl to bypass the lookup mechanism.

Can I use the gas_status tool with custom Arbitrum Orbit chains?

Yes. While the built-in ChainLookupService maps common names like "Arbitrum One" and "Xai", you can monitor any EVM-compatible chain—including custom Arbitrum Orbit deployments—by passing the explicit rpcUrl parameter to the gas_status tool.

What happens when the RPC endpoint is unreachable?

The ArbitrumChainClient.getGasStatus() method catches RPC failures and returns a default GasStatus object with currentGasPrice set to "0", currentGasPriceGwei set to "0", and a summary field containing the error message. This allows your monitoring scripts to detect outages without throwing unhandled exceptions.

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