> For the complete documentation index, see [llms.txt](https://docs.pharos.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.xyz/tooling-and-infrastructure/mcp.md).

# Pharos MCP

## Overview

The Pharos MCP server brings Pharos chain data and onchain operations into any client that speaks the [Model Context Protocol](https://modelcontextprotocol.io) — Claude Desktop, Cursor, Windsurf, Codex, and custom agent runners.

Instead of writing RPC plumbing, you ask your AI assistant in plain language — *"what's the latest Pharos block?"*, *"check the PROS balance of 0x…"* — and it calls the right chain method for you.

|                     |                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------- |
| **Hosted endpoint** | `https://mcp.pharos.xyz/mcp`                                                       |
| **Transport**       | Streamable HTTP                                                                    |
| **Authentication**  | None — public                                                                      |
| **Rate limit**      | 120 requests per minute per IP                                                     |
| **Chain ID**        | `1672` (`0x688`)                                                                   |
| **Native token**    | PROS                                                                               |
| **Source**          | [github.com/PharosNetwork/pharos-mcp](https://github.com/PharosNetwork/pharos-mcp) |

## Quick Start

Add the server to your MCP client configuration:

```json
{
  "mcpServers": {
    "pharos": {
      "type": "http",
      "url": "https://mcp.pharos.xyz/mcp"
    }
  }
}
```

No API key is required.

### Clients that only support stdio

Some clients cannot connect to remote MCP servers directly. Bridge to the hosted endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "pharos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.pharos.xyz/mcp"]
    }
  }
}
```

### Verify the connection

```bash
curl https://mcp.pharos.xyz/health
```

```json
{"status":"ok","chain":"Pharos","chainId":1672,"rpcUrl":"https://rpc.pharos.xyz"}
```

## Available Tools

### Chain and block data

| Tool               | JSON-RPC method                                        | Description                               |
| ------------------ | ------------------------------------------------------ | ----------------------------------------- |
| `get_chain_info`   | `eth_chainId`, `eth_blockNumber`, `web3_clientVersion` | Chain ID, client version and latest block |
| `get_block_number` | `eth_blockNumber`                                      | Latest block height                       |
| `get_block`        | `eth_getBlockByNumber`                                 | Block by tag or number                    |
| `get_gas_price`    | `eth_gasPrice`, `eth_maxPriorityFeePerGas`             | Current gas price and priority fee        |

### Accounts and transactions

| Tool                      | JSON-RPC method             | Description                       |
| ------------------------- | --------------------------- | --------------------------------- |
| `get_balance`             | `eth_getBalance`            | Native PROS balance of an address |
| `get_transaction_count`   | `eth_getTransactionCount`   | Address nonce                     |
| `get_transaction`         | `eth_getTransactionByHash`  | Transaction by hash               |
| `get_transaction_receipt` | `eth_getTransactionReceipt` | Transaction receipt               |

### Contracts

| Tool             | JSON-RPC method    | Description                           |
| ---------------- | ------------------ | ------------------------------------- |
| `eth_call`       | `eth_call`         | Read-only contract call               |
| `estimate_gas`   | `eth_estimateGas`  | Estimate gas without sending          |
| `get_code`       | `eth_getCode`      | Contract bytecode                     |
| `get_storage_at` | `eth_getStorageAt` | Read a contract storage slot          |
| `get_logs`       | `eth_getLogs`      | Event logs (max 1000 blocks per call) |

### Broadcasting

| Tool                   | JSON-RPC method          | Description                             |
| ---------------------- | ------------------------ | --------------------------------------- |
| `send_raw_transaction` | `eth_sendRawTransaction` | Broadcast an already-signed transaction |

## Block Parameters

Tools that accept a `block` parameter take any of:

* A named tag: `latest`, `earliest`, `pending`, `safe`, `finalized`
* A decimal number: `13005874`
* A hex quantity: `0xc67432`

Omitting it defaults to `latest`.

## Querying Event Logs

`get_logs` is capped at **1000 blocks per call**, matching the upstream RPC limit. Requests spanning a wider range are rejected with a message telling you the requested size and the maximum, so page through larger ranges in 1000-block windows.

Narrow results with `address` and `topics` wherever possible — an unfiltered query over a wide range is slow for everyone.

## Sending Transactions

The server is **non-custodial**: it never receives, stores, or asks for a private key. Signing happens entirely in your own wallet or script; the server only relays the resulting signed bytes to the network.

```
Your private key ──sign (locally)──▶ 0x02f86b…──▶ MCP server ──▶ Pharos
```

The flow is:

1. Build and sign a transaction locally with your own tooling (viem, ethers, a wallet).
2. Pass the resulting `0x`-prefixed string to `send_raw_transaction`.
3. Use the returned transaction hash with `get_transaction_receipt` to confirm inclusion.

Because signing is local, an AI agent connected to this server can prepare and broadcast a transaction for you without ever having access to your key.

## Self-Hosting

Run your own instance when you need a private RPC provider, a higher rate limit, or your own operational control.

Requires Node.js 20 or newer.

```bash
git clone https://github.com/PharosNetwork/pharos-mcp.git
cd pharos-mcp
npm install
npm run build
npm start
```

### Connecting a local instance over stdio

```json
{
  "mcpServers": {
    "pharos": {
      "command": "node",
      "args": ["/absolute/path/to/pharos-mcp/dist/src/index.js"],
      "env": {
        "PHAROS_RPC_URL": "https://rpc.pharos.xyz",
        "PHAROS_CHAIN_ID": "1672",
        "PHAROS_NATIVE_SYMBOL": "PROS"
      }
    }
  }
}
```

### Using your own RPC endpoint

Point `PHAROS_RPC_URL` at any Pharos RPC — including a provider endpoint that carries an API key, or your own node:

```json
"env": {
  "PHAROS_RPC_URL": "https://your-provider.example/v2/YOUR_API_KEY"
}
```

Keep such a URL out of version control; it holds a credential.

### Docker

```bash
docker build -t pharos-mcp-server .
docker run -p 3001:3001 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  pharos-mcp-server
```

### Configuration

| Variable                      | Default                  | Description                                                                          |
| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
| `PHAROS_RPC_URL`              | `https://rpc.pharos.xyz` | Upstream JSON-RPC endpoint                                                           |
| `PHAROS_CHAIN_ID`             | `1672`                   | Expected chain ID                                                                    |
| `PHAROS_NATIVE_SYMBOL`        | `PROS`                   | Native token symbol                                                                  |
| `MCP_TRANSPORT`               | `stdio`                  | `stdio` or `http`                                                                    |
| `MCP_HOST`                    | `127.0.0.1`              | Bind address; use `0.0.0.0` in containers                                            |
| `MCP_PORT`                    | `3001`                   | HTTP port                                                                            |
| `MCP_AUTH_TOKEN`              | —                        | Bearer token; authentication is off when unset                                       |
| `ENABLE_SEND_RAW_TRANSACTION` | `false`                  | Enable transaction broadcasting                                                      |
| `RATE_LIMIT_PER_MINUTE`       | `120`                    | Per-IP request cap; `0` disables                                                     |
| `TRUST_PROXY`                 | `false`                  | Set `true` behind exactly one trusted proxy so rate limiting sees the real client IP |
| `MAX_SESSIONS`                | `500`                    | Maximum concurrent sessions; further sessions get `503`                              |
| `SESSION_TIMEOUT_MINUTES`     | `30`                     | Idle session eviction time                                                           |

## Security Notes

* The server has no use for a private key or mnemonic — never pass one to it.
* `send_raw_transaction` is disabled by default in self-hosted deployments. If you enable it on a publicly reachable instance, put authentication in front of it first; an open broadcast endpoint lets anyone push transactions through your node.
* Set `MCP_AUTH_TOKEN` and terminate TLS in front of any instance you expose beyond localhost.
* `admin_*`, `debug_*`, `personal_*` and `txpool_*` methods are not exposed.

## Troubleshooting

| Symptom                 | Cause and fix                                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Unknown MCP session`   | The session expired or the server restarted. Reconnect the client — a full client restart clears cached session state.                             |
| `429 Too Many Requests` | Rate limit reached. Back off and retry after the interval in the `Retry-After` header, or self-host for a higher limit.                            |
| `Block range too large` | `get_logs` was called with more than 1000 blocks. Page through the range in smaller windows.                                                       |
| `Connection failed`     | The client may not support remote MCP servers. If it connects but lists no tools, this is the same cause. Bridge with `mcp-remote` as shown above. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.pharos.xyz/tooling-and-infrastructure/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.