RouteMesh MCP Server

@routemesh/mcp is a local stdio MCP server for querying blockchain data through RouteMesh.

At a glance

• Query multiple EVM chains from one MCP server.

• Pull useful on-chain data quickly (blocks, txs, logs, balances, fees).

• Compare live RPC and WebSocket service prices before choosing a route.

• Inspect account balance, usage by chain/method/key, and manage API keys with a management token.

• Use generic JSON-RPC when you need methods beyond built-in tools.

• Reduce RPC endpoint management overhead with RouteMesh routing + failover.

• Plug into Cursor as an on-demand command, not a background daemon.

Related MCP server: Nodeflare-mcp

Prompt examples

• "List chains that match base and show me their chain IDs."

• "Get the latest block on BSC and summarize timestamp + tx count."

• "Fetch receipt for tx 0x... on Ethereum and tell me if it succeeded."

• "Get logs for this contract on Arbitrum between block X and Y."

• "Estimate gas for calling this method on Base using these params."

• "Run eth_getCode on chain 8453 for address 0x...."

• "Show my RouteMesh usage for the last 7 days broken down by chain."

• "What is my current RouteMesh balance and request count this month?"

• "Compare economy and performance prices for eth_call on Base."

• "What does a million newHeads notifications on Ethereum cost?"

• "List my RouteMesh provider plans and the methods on each plan."

Tools

• rpc_list_chains - discover and filter supported chains (via GET /chains on the API server)

• rpc_get_pricing - published USD per million RPC requests, filtered by chain, method, and routing strategy

• rpc_get_ws_pricing - published USD per million WebSocket notifications, filtered by chain and subscription type

• rpc_call - generic JSON-RPC escape hatch

• rpc_get_block - fetch by number/tag/hash

• rpc_get_transaction - fetch transaction by hash

• rpc_get_transaction_receipt - fetch receipt by hash

• rpc_get_logs - query logs with block/topic filters

• rpc_get_balance - native token balance for an address

• rpc_call_contract - read-only eth_call

• rpc_estimate_gas - gas estimation

• rpc_get_fee_data - gas price + EIP-1559 hints

• rpc_trace_transaction - trace/debug transaction best effort

• get_usage - customer usage summary and balance from the API server (requires management token)

• list_api_keys - list customer API keys (requires management token)

• create_api_key - create a new API key with allowed domains and routing strategy (requires management token)

• update_api_key - update an existing API key (requires management token)

• provider_list_plans - list the provider's RPC plans (requires provider-linked management token)

• provider_get_plan_methods - list the RPC methods of one of the provider's plans (requires provider-linked management token)

• provider_upsert_plan_methods - insert/update the RPC method rows for a provider plan (requires provider-linked management token)

• provider_get_node_status - sync status of one of the provider's nodes (requires provider-linked management token)

• provider_upsert_node - create/update an HTTP node on a provider plan (requires provider-linked management token)

• provider_upsert_ws_node - create/update a WebSocket node on a provider plan (requires provider-linked management token)

• provider_set_node_status - enable/disable/delete a provider node (requires provider-linked management token)

Pricing tools

rpc_get_pricing accepts a required numeric chainId, optional method, and optional routingStrategy (economy or performance). Omit the strategy to compare both. It reads GET /pricing/rpc and returns currency: "USD", unit: "per_million_requests", and items containing the published route prices.

rpc_get_ws_pricing accepts a required numeric chainId and optional subscriptionType (for example newHeads or logs). It reads GET /pricing/ws and returns unit: "per_million_notifications".

Both endpoints are public: no management token is needed and credentials are not forwarded to them. The MCP process still requires its usual RPC API key configuration. Prices describe the RPC service, not blockchain gas fees or account-specific discounts. Empty results mean no matching published price, not a zero price. Pricing endpoints are rate-limited; tools report HTTP errors such as 429 and 503.

For direct HTTP calls, account authentication, and example workflows, see AI agents and automation. The OpenAPI reference describes the management and public APIs.

Customer tools

When ROUTEMESH_MGMT_TOKEN is set, the server exposes customer-scoped tools that call the API server with the management token in the x-api-key header.

Create a management token in the RouteMesh dashboard (Mgmt Tokens page): click New Token, give it a label (e.g. mcp), and copy the secret — it is shown only once.

Customer management tokens are scoped automatically to the customer management routes (GET /usage, GET /api-keys, POST /api-keys, PUT /api-keys/:id). There is no route allowlist to configure — use a dedicated token for the MCP server so you can revoke it independently.

Provider tools additionally require the token's customer to be linked to a provider; they are then scoped automatically to /provider/* routes, and resources owned by another provider come back as 404.

Add ROUTEMESH_MGMT_TOKEN beside ROUTEMESH_API_KEY in your MCP client configuration and restart the server.

get_usage — usage summary and balance

get_usage fetches customer usage data from the API server (GET /usage).

Examples:

• Default (last 30 days, summary + balance): call get_usage with no parameters

• Custom window with chain breakdown: from=2026-06-01T00:00:00Z, to=2026-06-18T00:00:00Z, include=["summary","by_chain"]

• Hourly time series for one API key: include=["time_series"], granularity="hour", apiKeyId=42

• Top methods on a chain: include=["top_methods"], chainId="1", limit=10

• Flat grouped rows: groupBy="api_key,chain", limit=50

list_api_keys — list API keys

list_api_keys calls GET /api-keys and returns an array of API key metadata (id, name, active, allowed_domains, routing_strategy, timestamps). The secret api_key value is never returned by this endpoint.

create_api_key — create a new API key

create_api_key calls POST /api-keys to provision a new key. The request requires:

Important: The response includes the secret api_key value, which is only shown once at creation. Store it securely — it cannot be retrieved again.

update_api_key — update an existing API key

update_api_key calls PUT /api-keys/:id for partial updates. If your integration previously passed an apiKey secret, switch to the numeric id returned by list_api_keys:

At least one of name, active, or allowed_domains must be provided. The secret api_key value is never returned by this endpoint.

Provider tools

Provider tools mirror the provider-scoped API routes (/provider/*) and require a management token whose customer is linked to a provider. All writes are ownership-checked server-side: a plan_id / node that belongs to another provider is rejected (404), so tools can only affect the linked provider's own resources.

provider_list_plans — list the provider's plans

Calls GET /provider/plans. Returns the provider's plans (id, name, price, quota, rate limits, billing fields) or an empty array.

provider_get_plan_methods — list a plan's RPC methods

Calls GET /provider/plans/:planId/methods.

Returns the plan's RPC method rows (method, vm, node_target_type, cost, rate limits, chain_id) or an empty array.

provider_upsert_plan_methods — insert/update a plan's RPC methods

Calls POST /provider/plans/:planId/methods.

Each methods[] item supports: method, vm, node_target_type, cost, optional rate_limit, optional rate_limit_interval_sec, and optional chain_id (omit/null for all chains). Returns a plain-text success message on 201.

provider_get_node_status — node sync status

Calls GET /provider/nodes/:nodeId/status.

Returns { node_id, in_sync, status } where status is ok or out_of_sync.

provider_upsert_node — create/update an HTTP node

Calls PUT /provider/nodes. The node is screened server-side; mandatory screening failures are returned as 400. The URL must be a public http:// or https:// endpoint; loopback, private (10/8, 172.16/12, 192.168/16), and link-local (169.254/16) addresses are rejected client-side before forwarding.

provider_upsert_ws_node — create/update a WebSocket node

Calls PUT /provider/nodes/ws. The server dials the node and verifies it accepts eth_subscribe (newHeads) before persisting. The URL must be a public wss:// endpoint; loopback, private, and link-local addresses are rejected client-side before forwarding.

provider_set_node_status — enable/disable/delete a node

Calls POST /provider/nodes/status.

Prerequisites

• Node.js 20+

• RouteMesh API key (sign up)

• Customer management token (optional, for account balance, usage, and key management)

Quick start

Install and build:

npm install
npm run build

Set API key for local dev:

cp .env.example .env

Run local build:

ROUTEMESH_API_KEY=your_key_here node dist/index.js

Run in dev mode:

ROUTEMESH_API_KEY=your_key_here npm run dev

Run published package:

ROUTEMESH_API_KEY=your_key_here npx -y @routemesh/mcp

Cursor MCP config

Add one of these to ~/.cursor/mcp.json.

Local build:

{
  "mcpServers": {
    "routemesh": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/PROJECT/dist/index.js"],
      "env": {
        "ROUTEMESH_API_KEY": "replace-with-your-routemesh-key",
        "ROUTEMESH_MGMT_TOKEN": "replace-with-your-customer-mgmt-token"
      }
    }
  }
}

Published package via npx:

{
  "mcpServers": {
    "routemesh": {
      "command": "npx",
      "args": ["-y", "@routemesh/mcp"],
      "env": {
        "ROUTEMESH_API_KEY": "replace-with-your-routemesh-key",
        "ROUTEMESH_MGMT_TOKEN": "replace-with-your-customer-mgmt-token"
      }
    }
  }
}

Development commands

• npm run typecheck - static type checking

• npm run test - run tests once

• npm run test:watch - watch mode

• npm run build - compile to dist/

Release

npm run test
npm run build
npm version patch
npm publish --access public

Notes

• The server is read-only for on-chain RPC tools.

• get_usage reads billing/usage data from the API server; it does not use Atlas.

• Requests use ROUTEMESH_BASE_URL first, then ROUTEMESH_BACKUP_BASE_URL on retryable failures.

• rpc_list_chains reads chain data from GET /chains on the API server (ROUTEMESH_API_SERVER_URL).

References

• RouteMesh docs: https://routeme.sh/docs