# 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

```plaintext
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

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

#### Response

```json
{
  "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:

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

Response:

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

***

### Server Setup

To run `chainlist-mcp` locally:

```bash
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`:

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

***

### Data Sources

By default, `chainlist-mcp` pulls from:

* [chainlist.org](https://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

```bash
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pil.so/mcp-server-models/chainlist-mcp-chain-info.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.