chainlist-mcp: Chain Info

The chainlist-mcp server provides agents with accurate, up-to-date information about supported blockchain networks. It allows LLM agents to resolve key chain metadata, such as:

• Chain ID

• Native currency symbol

• RPC URL

• Explorer base URL

• Network name

This is critical for ensuring that downstream tool calls (like metamask.sign or erc20.transfer) operate on the correct chain with the correct parameters.

---

What It Does

• Maps chain names (e.g. "optimism", "arbitrum") to network metadata

• Retrieves RPC URLs, explorer URLs, chain IDs

• Acts as a read-only reference service — no state mutation, no signing

• Prevents misrouting or misuse of MCP tools due to missing or incorrect network info

---

Architecture

Agent → chainlist-mcp → Chain Metadata → Other tools (signer, bridge, erc20)

This server acts as a metadata fetcher for the rest of the MCP pipeline. It helps tools like metamask-mcp and erc20-mcp by resolving the correct RPC, chain ID, and explorer info before they construct or sign any transaction.

---

Tool Name: chainlist.getChain

Request

{
  "tool": "chainlist.getChain",
  "args": {
    "name": "base"
  }
}

Response

{
  "name": "Base",
  "chainId": 8453,
  "rpc": "https://mainnet.base.org",
  "explorer": "https://basescan.org",
  "currency": "ETH",
  "network": "base-mainnet"
}

---

Tool Name: chainlist.getRPC

Shortcut to retrieve only the RPC URL:

{
  "tool": "chainlist.getRPC",
  "args": {
    "name": "optimism"
  }
}

Response:

{
  "rpc": "https://mainnet.optimism.io"
}

---

Server Setup

To run chainlist-mcp locally:

git clone https://github.com/pilso-os/mcp-servers
cd mcp-servers/chainlist-mcp
npm install
npm start

Default endpoint: http://localhost:3030

Add it to your pilso.config.json:

"tools": [
  "http://localhost:3030"
]

---

Data Sources

By default, chainlist-mcp pulls from:

• chainlist.org JSON API

• Local fallback file for offline dev

This ensures agents can function even in low-connectivity environments (e.g., testing environments or CI).

---

Test Call Locally

npx pilso call \
  --tool chainlist.getChain \
  --args '{"name": "polygon"}'

Returns full chain metadata, including RPC, chain ID, and currency.

---

Chains Best Practices

• Only expose this tool to agents that need multi-chain context (e.g. swapper, deployer)

• Use this tool before calling metamask.sign, erc20.transfer, etc

• Do not hardcode RPCs — use chainlist.getRPC for reliable resolution

• Cache chain metadata in long-lived agents to reduce redundancy

---

Future Additions

• Add support for custom chain overrides via local config

• Chain capability resolution (e.g. "can this chain bridge?", "supports EIP-1559?")

• RPC reliability score (filter fallback RPCs by latency)

---

✅ Summary

Property	Value
Tool names	chainlist.getChain, chainlist.getRPC
Port	3030 (default)
Signature	No — read-only
Required for	All tools that need chain info or RPCs
Security	Fully isolated — no signing, no mutations

The chainlist-mcp module helps agents stay oriented in a multi-chain world — enabling trustless infrastructure that works across networks without manual config.