Pharos MCP Server

An MCP server that brings Pharos chain data into MCP-compatible IDEs and agent workflows — Claude Desktop, Cursor, Windsurf, and custom agent runners.

• Network: Pharos (EVM-compatible, 100% Ethereum-compatible)
• Chain ID: 1672 (0x688)
• RPC: https://rpc.pharos.xyz
• Native token: PROS
• Hosted endpoint: https://mcp.pharos.xyz/mcp

Quick start — use the hosted server

No API key required. Add this to your MCP client configuration:

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

The hosted endpoint speaks Streamable HTTP, so your client must support remote MCP servers. Clients that only support stdio can bridge with mcp-remote:

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

Once connected, ask your agent things like "what's the latest Pharos block?" or "check the PROS balance of 0x…".

Rate limit: 120 requests per minute per IP. Exceeding it returns HTTP 429 with a Retry-After header.

Tools

13 read-only tools are available today.

Tool	Underlying JSON-RPC	Description	Parameters
get_chain_info	eth_chainId, eth_blockNumber, web3_clientVersion	Chain ID, client version, latest block	—
get_block_number	eth_blockNumber	Latest block height	—
get_balance	eth_getBalance	Native PROS balance of an address	address, block?
get_transaction_count	eth_getTransactionCount	Address nonce	address, block?
get_gas_price	eth_gasPrice, eth_maxPriorityFeePerGas	Current gas price and priority fee	—
get_block	eth_getBlockByNumber	Block by tag or number	block?, includeTransactions?
get_transaction	eth_getTransactionByHash	Transaction by hash	hash
get_transaction_receipt	eth_getTransactionReceipt	Transaction receipt	hash
get_code	eth_getCode	Contract bytecode	address, block?
get_storage_at	eth_getStorageAt	Read a contract storage slot	address, position, block?
eth_call	eth_call	Read-only contract call	transaction, block?
estimate_gas	eth_estimateGas	Estimate gas without sending	transaction
get_logs	eth_getLogs	Event logs over a block range (max 5000 blocks per call)	address?, topics?, fromBlock?, toBlock?

block accepts a named tag (latest, earliest, pending, safe, finalized), a decimal number, or a 0x hex quantity.

Transaction broadcasting

A send_raw_transaction tool exists but is disabled on the hosted endpoint (ENABLE_SEND_RAW_TRANSACTION=false), which is therefore read-only. Calling it there returns an error.

The design is non-custodial: the server never receives or stores a private key. It only relays a transaction you already signed locally. If you self-host and enable it, put authentication in front of the endpoint first — an open, unauthenticated broadcast endpoint lets anyone push transactions through your node.

Self-hosting

Requires Node.js 20+.

npm install
npm run build

stdio transport

npm start

{
  "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"
      }
    }
  }
}

HTTP transport

MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_PORT=3001 \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npm start

• MCP endpoint: http://127.0.0.1:3001/mcp (POST only)
• Health check: http://127.0.0.1:3001/health

With MCP_AUTH_TOKEN set, clients must send Authorization: Bearer <token>.

Scaling note. In HTTP mode each MCP session is held in the server process's memory. Running multiple instances behind a load balancer therefore needs real session affinity — and cookie-based stickiness is not enough, because MCP clients generally do not store or resend cookies. Requests that land on an instance which does not own the session fail with Unknown MCP session. Run a single instance, or move session state into a shared store before scaling out.

Docker

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; auth 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 when running behind exactly one trusted proxy (e.g. an ALB) so rate limiting uses the real client IP. Leave false if the server is directly reachable — otherwise clients can spoof X-Forwarded-For and evade the limiter
MAX_SESSIONS	500	Maximum concurrent MCP sessions; new sessions past the cap get 503. 0 disables the cap
SESSION_TIMEOUT_MINUTES	30	Idle sessions are evicted after this long

Development

npm test           # unit tests + a live chain ID check
npm run smoke      # end-to-end MCP test over stdio against the real RPC
npm run smoke:http # end-to-end test against a running HTTP server

npm run smoke exercises the write path by signing a zero-value transaction with a freshly generated empty wallet. The RPC rejects it for insufficient funds, so nothing is broadcast on-chain.

Security notes

• Never pass a private key or mnemonic to this server; it has no use for one.
• send_raw_transaction is disabled by default.
• HTTP binds to 127.0.0.1 by default.
• For a public deployment, terminate TLS in front of the server and keep rate limiting on.
• admin_*, debug_*, personal_* and txpool_* methods are not exposed.

License

MIT