# Rialto Swap MCP (read-only)

Read-only MCP service for Rialto — the onchain best-execution swap router on
Robinhood Chain (chain id 4663) for crypto and tokenized equities, ETFs, and
commodities. It deliberately contains **no** submit, execute, signing, or
wallet tool — quoting and pricing only.

Hoodly's own agents get real swap execution through a native, server-wallet
tool pair inside the Hoodly API (`rialto_read` / `rialto_action` in
`api-hoodly`), not through this MCP. This project exists for any other MCP
client — Claude Desktop, an inspector, a third-party agent — that wants
Rialto pricing without building the API integration itself.

## Tools

- `rialto_list_tokens` — every token quotable on Rialto for Robinhood Chain (symbol, address, decimals, type). Public, no key needed.
- `rialto_get_quote` — best-execution quote: expected output, guaranteed minimum, every fee line, route stats, blockers. Requires `RIALTO_API_KEY`.
- `rialto_preflight` — validates a quote against baseline safety checks (balance/allowance issues, settlement sanity, staleness, slippage ceiling, fee cap, zero-output guard) before any signing step.
- `rialto_build_unsigned_tx` — returns the unsigned payload (tx + EIP-712 typed data + signature offset) for a **user-signed wallet** to complete elsewhere. This server never signs.

## Why no execute tool

Rialto's `/quote` and `/gasless/submit` responses carry real transactions —
`rialto_build_unsigned_tx` hands back exactly what a wallet needs to sign,
and stops there deliberately. Adding a submit/execute tool here would mean
either holding a private key in a generically-installable MCP process (a
step backwards from any reasonable custody boundary) or forwarding to some
external signer this project has no relationship with. Neither is
appropriate for a standalone, general-purpose MCP server. If your
integration needs to sign, sign in your own client with your own key
material, using `rialto_build_unsigned_tx`'s output.

## Environment

```bash
RIALTO_API_KEY=rialto_live_<prefix>.<secret>   # never logged, never committed
MCP_TRANSPORT=http                              # or stdio
PORT=3008                                       # http mode only
HOST=0.0.0.0                                    # http mode only
```

## Run it

```bash
npm install
npm run dev          # stdio: set MCP_TRANSPORT=stdio in .env first
```

```json
{
  "mcpServers": {
    "rialto": { "command": "node", "args": ["src/index.js"], "env": { "MCP_TRANSPORT": "stdio", "RIALTO_API_KEY": "..." } }
  }
}
```

## Run it with PM2

[ecosystem.config.cjs](ecosystem.config.cjs) runs the HTTP transport on port 3081. `RIALTO_API_KEY` still comes from `.env` (dotenv doesn't override vars PM2 already sets, so `PORT`/`HOST`/`MCP_TRANSPORT` in the config win, and the secret key stays out of the config file).

```bash
pm2 start ecosystem.config.cjs   # start
pm2 restart mcp-rialto           # after a code change
pm2 logs mcp-rialto              # tail logs
pm2 stop mcp-rialto              # stop
pm2 delete mcp-rialto            # remove from the pm2 process list
pm2 save                         # persist the process list across reboots
```

The matching local workflow is [SKILL.md](SKILL.md).