@rholabs/rho-mcp

A Model Context Protocol server for Rho Exchange — an interest-rate derivatives DEX. Works with Claude Code, Claude Desktop, Cursor, Zed, Windsurf, and any MCP-compatible AI agent.

26 tools: market data, account state, order management, and browser-based authorization (with whoami / logout / switch-account flow).

Quick install

Claude Code (one command)

claude mcp add rho-exchange -- npx -y @rholabs/rho-mcp@latest

That's it. The server connects to production by default. Authorize via browser when prompted — no API keys required.

The @latest tag makes npx re-resolve the package on every MCP host launch so you automatically pick up new releases when you restart your host — no manual updates, no stale npx cache. If you prefer a fixed version, replace @latest with the specific version (e.g. @0.1.3).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rho-exchange": {
      "command": "npx",
      "args": ["-y", "@rholabs/rho-mcp@latest"]
    }
  }
}

Cursor / Zed / other MCP hosts

Same pattern — set command: "npx" and args: ["-y", "@rholabs/rho-mcp@latest"] in your host's MCP configuration.

Already installed? Move to the latest version

If you added the server before @latest was in the install command, npx cached the first version it resolved and keeps serving it on every launch. Two ways to recover:

Preferred — update your MCP host config to use @latest. On Claude Code:

claude mcp remove rho-exchange
claude mcp add rho-exchange -- npx -y @rholabs/rho-mcp@latest

On Claude Desktop / Cursor / Zed, edit your host's MCP config and append @latest to the package name in args, then restart the host.

Alternative — clear the npx cache once:

rm -rf ~/.npm/_npx

This forces a fresh resolve on the next launch regardless of which command is in your config. Safe: npm re-downloads cached packages on demand.

After restarting your MCP host, check your host's server log for the startup banner [rho-mcp-gateway] vX.Y.Z — env vars detected: … to confirm which version you're running.

Authentication

Two methods, pick one:

Browser authorization (recommended for interactive use)

1. Add the MCP server (see above) — no credentials needed.
2. Ask the agent to do something that requires auth (e.g., "show my positions").
3. The agent runs the gateway_authorize tool — a browser window opens.
4. Log in with your wallet and click Approve.
5. Done. The token is saved to your OS keychain and reused across sessions.

API key (for bots / automation)

1. Go to x.rho.trading → Settings → API Keys → Create new key.
2. Pick a scope: ReadOnly or FullAccess.
3. Add with credentials:

claude mcp add rho-exchange \
  -e RHO_API_KEY=rho_your_key_here \
  -e RHO_API_SECRET=your_hex_secret_here \
  -- npx -y @rholabs/rho-mcp@latest

Or store keys in your OS keychain to avoid plaintext secrets:

# macOS
security add-generic-password -s rho-mcp -a key -w
security add-generic-password -s rho-mcp -a secret -w

# Linux (libsecret)
echo -n "rho_your_key_here" | secret-tool store --label="rho-mcp key" service rho-mcp account key
echo -n "your_hex_secret_here" | secret-tool store --label="rho-mcp secret" service rho-mcp account secret

Then add the server without env vars — it reads from keychain automatically.

Tools (26)

Gateway (4 tools)

| Tool | Purpose | |---|---| | gateway_health | Liveness check. Does not touch upstream. | | gateway_authorize | Opens a browser to authorize the MCP gateway with your rho-exchange account. Token saved to OS keychain. Also the path to switch accounts — running it again overwrites the saved token. | | gateway_whoami | Reports the current connection: auth mode, base URL, gateway version, redacted credential preview, and (for bearer tokens) the decoded user email if the JWT carries one. Use before placing trades when you have multiple accounts. | | gateway_logout | Clears the saved bearer token and API key from the OS keychain and drops the in-memory client. After this, all account/trading tools require a fresh gateway_authorize. Note: does not unset RHO_API_* env vars — to fully retire an API key, also remove it from the MCP host config and restart. |

Switching to a different rho-exchange account

• Bearer-token (browser) users: just run gateway_authorize again. The new browser flow overwrites the keychain entry and the in-memory client.
• Full disconnect: run gateway_logout, then gateway_authorize to reconnect (optionally as a different account).
• API-key users wanting to swap keys: API keys are read once at process startup. Remove the old RHO_API_KEY / RHO_API_SECRET from your MCP host config (or run gateway_logout to clear the keychain copy), set the new ones, and restart the MCP host.

Market data (8 tools, read-only)

| Tool | Purpose | |---|---| | market_get_exchange_info | Symbols, markets, currencies, margin templates, features. Start here. | | market_get_tickers | Last price, bid/ask, 24h volume, open interest for multiple symbols. | | market_get_ticker | Same, for a single symbol. | | market_get_order_book | Bid/ask depth snapshot. | | market_get_recent_trades | Recent public fills (market tape). | | market_get_candles | OHLCV candles for a symbol. | | market_get_floating_rate_candles | Floating-rate index candles — the defining data for IR derivatives. | | market_get_volume_stats | Aggregate exchange volume over a time window. |

Account (11 tools, read-only, authenticated)

| Tool | Purpose | |---|---| | account_get_total_account | Total PnL, free balance, fees, per-margin-account breakdown. | | account_get_account_candles | Equity curve of the whole account. | | account_get_balances | Currency balances across margin accounts. | | account_get_withdrawable_balances | Withdrawable amounts per margin account. | | account_get_open_orders | Currently working orders. | | account_get_positions | Open positions with PnL, dv01, liquidation rate. | | account_get_recent_trades | User's fill history. | | account_get_transfers | Deposit / withdrawal / margin-allocation history. | | account_list_margin_accounts | All margin accounts the user has. | | account_get_margin_account | Details of one margin account. | | account_get_margin_account_candles | Per-margin-account equity curve. |

Trading (3 tools, mutating, FullAccess scope required)

| Tool | Purpose | Destructive? | |---|---|---| | trade_place_order | Place a limit or market order. | No | | trade_cancel_order | Cancel one order by ID. | No (idempotent) | | trade_cancel_all_orders | Cancel all matching orders. Filters by symbol/side/margin account. | Yes — host will prompt for confirmation. |

Not included

• Withdrawals — requires wallet signature the agent cannot produce.
• WebSocket streams — MCP is request/response. Poll with account tools instead.

Environment variables

| Variable | Default | Description | |---|---|---| | RHO_API_BASE_URL | https://x.rho.trading/api/v1 | API endpoint. Override for other environments. | | RHO_API_KEY | — | API key (optional if using browser auth or keychain). | | RHO_API_SECRET | — | Hex-encoded HMAC secret (optional if using browser auth or keychain). | | RHO_BEARER_TOKEN | — | Bearer token (optional, usually managed automatically). | | RHO_CLIENT_URL | derived from API URL | Frontend URL for browser authorization. | | LOG_LEVEL | info | debug / info / warn / error. Logs to stderr. | | PORT | 8787 | HTTP server port (only for streamable-HTTP mode). |

Troubleshooting

rho-exchange ✘ failed in claude mcp list

Run claude mcp get rho-exchange for the error. Common causes:

• RHO_API_SECRET must be hex-encoded — wrong value in secret field. Re-create the key.
• 401 Invalid signature — key/secret mismatch. Regenerate.
• EACCES on keychain — run security find-generic-password -s rho-mcp -a key -w manually once to grant permission.

Session expired

If you see "Session expired. Run the gateway_authorize tool" — the bearer token has expired (7-day TTL). Just run gateway_authorize again.

Rate limits

Rate limits are keyed on your account. Relax polling cadence if you hit them.

Architecture

• Transport: stdio — the host spawns node dist/stdio.js, communicates via stdin/stdout JSON-RPC.
• Auth modes: API key + HMAC-SHA256 signature, or Bearer token from browser auth.
• Signing: TypeScript signer verified against Go middleware test vectors.
• Keychain: macOS Keychain / Linux libsecret for credential storage.
• Browser auth: Temporary localhost HTTP server for OAuth-like callback flow.

Development

git clone [email protected]:RhoLabs/rho-mcp.git
cd rho-mcp
npm install
npm run dev:stdio    # stdio mode with tsx
npm run dev          # HTTP mode with hot reload
npm test             # run tests
npm run build        # compile TypeScript

License

MIT