# @0xmonaco/mcp-server

MCP server for the Monaco SDK — gives AI assistants access to the Monaco protocol on Sei.

Works in **public-only mode** with zero configuration. Add a private key to enable
authenticated tools — scoped by a [capability profile](#capability-profiles) so that
supplying a key does **not** blindly unlock the entire tool set.

## Configuration

| Variable               | Required                     | Description                                |
|------------------------|------------------------------|--------------------------------------------|
| `MONACO_PRIVATE_KEY`   | No                           | Wallet private key (`0x...`) — enables authenticated tools        |
| `MONACO_CLIENT_ID`     | With `MONACO_PRIVATE_KEY`    | Monaco application client ID                                      |
| `MONACO_NETWORK`       | With `MONACO_PRIVATE_KEY`    | `mainnet` \| `development` \| `staging` \| `local`. **Must be explicit when a private key is set** — the server refuses to default to `mainnet` for an authenticated session. Defaults to `mainnet` only for public-only mode. |
| `MONACO_CAPABILITY`    | No                           | `read` \| `market-maker` \| `full`. Authenticated default: `read`. See [capability profiles](#capability-profiles). |
| `MONACO_TOOL_ALLOWLIST`| No                           | Comma-separated tool names to enable on top of the profile (explicit per-tool opt-in, e.g. a single fund-movement tool). |
| `MONACO_TOOL_DENYLIST` | No                           | Comma-separated tool names to disable. Wins over the profile and the allowlist. |
| `MONACO_RPC_URL`       | No                           | Sei RPC URL (defaults per network)                                |
| `MONACO_DELEGATED_OWNER_USER_ID` | No                 | Run on behalf of a delegated **owner** account. The `MONACO_PRIVATE_KEY` wallet is the agent; on startup it authenticates as itself, then adopts an owner-scoped session so every tool call acts on the owner (agent preserved as the audit actor). Requires `MONACO_PRIVATE_KEY` + `MONACO_CLIENT_ID`. See [delegated owner mode](#delegated-owner-mode). |

## Capability profiles

`MONACO_CAPABILITY` bounds which authenticated tools the server registers. A tool that
is not permitted by the active profile (and not named in `MONACO_TOOL_ALLOWLIST`) is
**never registered** — this is an authorization control, not an advisory tool
annotation.

| Profile        | Tools enabled                                                                 |
|----------------|-------------------------------------------------------------------------------|
| `read`         | Authenticated read-only queries — profile, balances, orders, movements, fee tier, vault allowance. No state changes. **Default when authenticated** — supplying a key alone grants no write authority. |
| `market-maker` | `read` + order placement / cancel / replace + the testnet faucet. Opt in to let an agent make markets. No fund movement. |
| `full`         | `market-maker` + fund movement and privilege mutations (vault approve/deposit/withdraw, `transfer_rewards`). Opt-in only. |

Order placement, cancel, replace, and close require `MONACO_CAPABILITY=market-maker` or
higher — the default `read` profile cannot mutate anything. Fund-movement and privilege
tools additionally require `full`; enable them with `MONACO_CAPABILITY=full`, or opt a
single tool in with `MONACO_TOOL_ALLOWLIST` (e.g. `MONACO_TOOL_ALLOWLIST=vault_withdraw`).
Grant `full` only when you intend an agent to move funds — especially on `mainnet`.

### Delegated owner mode

Set `MONACO_DELEGATED_OWNER_USER_ID` to act on behalf of a delegated owner account instead of
the configured wallet's own account. The wallet in `MONACO_PRIVATE_KEY` is the **agent**: on
startup it authenticates as itself, then adopts an owner-scoped delegated session
(`loginAsDelegatedOwner`). Every subsequent tool call — reads and trades — acts on the owner
account, with the agent wallet preserved as the actor for audit. The owner must have registered
this agent wallet with an active delegation policy; the server cannot self-assert ownership, and
adoption fails if the agent is not authorized for that owner.

This is fail-closed: `MONACO_DELEGATED_OWNER_USER_ID` requires `MONACO_PRIVATE_KEY` and
`MONACO_CLIENT_ID`, a blank value is rejected, and if owner adoption fails the server does not
fall back to trading as the agent's own account. Fund-movement tools still require the `full`
capability, and delegated sessions cannot withdraw owner collateral. Raw delegated-session
creation is intentionally not exposed as a tool — owner adoption is a startup option, not an
autonomous agent action.

### Networks

For public endpoints, set `MONACO_NETWORK` to one of the following documented values:

| Network             | API URL                         | Default RPC URL                        |
|---------------------|---------------------------------|----------------------------------------|
| `mainnet` (default) | `https://api.monaco.xyz`        | `https://evm-rpc.sei-apis.com`         |
| `staging`           | `https://staging.apimonaco.xyz` | `https://evm-rpc-testnet.sei-apis.com` |

## Installation

Add the following to your MCP config:

- **Cursor** — `~/.cursor/mcp.json`
- **Windsurf** — `~/.codeium/windsurf/mcp_config.json`
- **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)

### Public-only mode (no env vars needed)

Market data, orderbook, trades, and docs search — no wallet required.

```json
{
  "mcpServers": {
    "monaco": {
      "command": "npx",
      "args": ["-y", "@0xmonaco/mcp-server"]
    }
  }
}
```

### Authenticated mode

Authenticated read-only tools under the default `read` profile. `MONACO_NETWORK` is
**required** here — the server will not default an authenticated session to `mainnet`.

```json
{
  "mcpServers": {
    "monaco": {
      "command": "npx",
      "args": ["-y", "@0xmonaco/mcp-server"],
      "env": {
        "MONACO_NETWORK": "staging",
        "MONACO_PRIVATE_KEY": "0x...",
        "MONACO_CLIENT_ID": "your-client-id"
      }
    }
  }
}
```

Trading and fund movement stay **off** here. Add `"MONACO_CAPABILITY": "market-maker"`
to place / cancel / replace orders, or `"MONACO_CAPABILITY": "full"` to also enable
fund-movement tools (vault deposit/withdraw, `transfer_rewards`). A single fund-movement
tool can be opted in with `"MONACO_TOOL_ALLOWLIST": "vault_withdraw"` instead of `full`.
RPC URLs default automatically per network but can be overridden with `MONACO_RPC_URL`.

## Tools

Public tools require no credentials. Authenticated tools require `MONACO_PRIVATE_KEY`,
`MONACO_CLIENT_ID`, and `MONACO_NETWORK`, and are further gated by the active
[capability profile](#capability-profiles) — the profile column shows the minimum
profile each tool needs.

<!-- BEGIN GENERATED TOOLS — source: typescript-sdks/packages/mcp-server/src/manifest.ts; regenerate with `bun run mcp-docs:gen` -->

### Search

| Tool | Profile | Description |
|------|---------|-------------|
| `search_docs` | Public | Search the Monaco documentation for protocol, SDK, trading, and development guides. |

### Market

| Tool | Profile | Description |
|------|---------|-------------|
| `get_trading_pairs` | Public | List trading pairs with optional filters (market type, base/quote token, active status). |
| `get_trading_pair_by_symbol` | Public | Look up a trading pair by symbol (e.g. `BTC/USDC`). |
| `get_candlesticks` | Public | Fetch OHLCV candlestick data for a trading pair. |
| `get_market_metadata` | Public | Get tick size, minimum order size, and trading rules for a pair. |
| `get_screener` | Public | Screen trading pairs with market stats (price, volume, change), filtered by market type, category, and active status. |
| `get_market_stats` | Public | Get exchange-wide life-to-date cumulative volume and trade count across all markets. |

### Perp market data

| Tool | Profile | Description |
|------|---------|-------------|
| `get_perp_market_config` | Public | Get a perpetual market's configuration (leverage limits, margin requirements, funding parameters). |
| `get_perp_market_summary` | Public | Get a perpetual market's live summary (mark/index price, funding rate, open interest, 24h stats). |
| `get_mark_price` | Public | Get the current mark price for a perpetual market. |
| `get_index_price` | Public | Get the current index (oracle) price for a perpetual market. |
| `get_funding_state` | Public | Get the current funding rate and next funding time for a perpetual market. |
| `get_open_interest` | Public | Get the current open interest for a perpetual market. |
| `get_funding_history` | Public | List historical funding-rate records for a perpetual market. |
| `get_all_funding_history` | Public | List historical funding-rate records across all perpetual markets. |

### Orderbook

| Tool | Profile | Description |
|------|---------|-------------|
| `get_orderbook` | Public | Fetch a current orderbook snapshot with bids and asks. |

### Trades

| Tool | Profile | Description |
|------|---------|-------------|
| `get_trades` | Public | Fetch historical trades for a trading pair. |

### Trading

Order reads (`get_orders`, `get_order`) are available under `read`; the mutations below require `market-maker` or higher.

| Tool | Profile | Description |
|------|---------|-------------|
| `place_limit_order` | `market-maker` | Place a limit order with price, quantity, and time-in-force. The SDK supplies an idempotency key if omitted. Retain an explicit key to retry the same submission within 24 hours of acceptance. Calling again without the original key is not idempotent; never retry an ambiguous failure with a new key. If the original key is unavailable, report the ambiguity. |
| `place_market_order` | `market-maker` | Place a market order — executes immediately inside a mandatory 1,000 bps protective price band, so it may partially fill or be rejected. The SDK supplies an idempotency key if omitted. Retain an explicit key to retry the same submission within 24 hours of acceptance. Calling again without the original key is not idempotent; never retry an ambiguous failure with a new key. If the original key is unavailable, report the ambiguity. |
| `replace_order` | `market-maker` | Modify an existing order's price and/or quantity. Not idempotent — an ambiguous failure (timeout/network error/5xx with no order) cannot be resolved from inside MCP, which has no order-stream tool; never retry, and report the ambiguity instead. |
| `cancel_order` | `market-maker` | Cancel a single order by ID. |
| `batch_cancel_orders` | `market-maker` | Cancel multiple orders by ID (non-atomic — a failed leg does not stop the others). |
| `batch_cancel_all_orders` | `market-maker` | Cancel all open orders, optionally filtered to a trading pair (unfiltered, it cancels your entire open-order book). |
| `batch_close_all_positions` | `market-maker` | Close all open perpetual positions with market reduce-only orders (best-effort, optional pair filter). |
| `get_orders` | `read` | List your orders with optional filters. |
| `get_order` | `read` | Get details for a specific order by ID. |

### Positions

Position reads are available under `read`; `close_position` requires `market-maker`, and margin add/reduce move collateral and require `full`.

| Tool | Profile | Description |
|------|---------|-------------|
| `get_positions` | `read` | List your perpetual positions with optional filters (margin account, trading pair, status). |
| `get_position` | `read` | Get details for a specific perpetual position by ID. |
| `get_position_risk` | `read` | Get liquidation price, margin ratio, and risk metrics for a perpetual position. |
| `get_position_history` | `read` | List historical (closed/reduced) perpetual position records with optional filters. |
| `get_position_pnl_history` | `read` | Get the PnL history time series for a perpetual position over an interval. |
| `close_position` | `market-maker` | Close a perpetual position with a market, limit, or IOC reduce order. |

### Portfolio

| Tool | Profile | Description |
|------|---------|-------------|
| `get_portfolio_summary` | `read` | Get your authoritative portfolio summary (equity, PnL, exposure) over a period. |
| `get_portfolio_performance` | `read` | Get your portfolio performance time series over a period. |
| `get_portfolio_realized_pnl` | `read` | Get your realized PnL breakdown over a period. |
| `get_portfolio_assets` | `read` | Get your per-asset portfolio allocation and balances over a period. |
| `get_portfolio_margin` | `read` | Get your portfolio margin overview (collateral, maintenance margin, health). |

### Margin accounts

Reads and risk simulations are available under `read`; collateral transfers move funds and require the `full` profile (or an explicit allowlist entry).

| Tool | Profile | Description |
|------|---------|-------------|
| `get_margin_accounts` | `read` | List your margin accounts with optional filters (state, trading pair). |
| `get_parent_margin_account_summary` | `read` | Get your parent (cross) margin account summary. |
| `get_available_collateral` | `read` | Get available (unlocked) collateral for allocating to margin accounts or risk buckets. |
| `get_parent_margin_account_movements` | `read` | List collateral movements for your parent (cross) margin account. |
| `simulate_parent_margin_order_risk` | `read` | Preview the risk impact of a prospective order against your parent (cross) margin account (read-only simulation). |
| `simulate_risk_bucket_order_risk` | `read` | Preview the risk impact of a prospective order for a new or existing risk bucket (read-only simulation). |
| `transfer_collateral_to_parent_margin_account` | `full` | Move collateral from spot into your parent (cross) margin account. |
| `transfer_collateral_from_parent_margin_account` | `full` | Move collateral out of your parent (cross) margin account back to spot. |
| `transfer_collateral_to_risk_bucket` | `full` | Allocate collateral into an isolated or cross risk bucket. |

### Profile

| Tool | Profile | Description |
|------|---------|-------------|
| `get_profile` | `read` | Fetch your core profile (address, username, account type, withdrawal status). |
| `get_balances` | `read` | List token balances with pagination. |
| `get_balance_by_asset` | `read` | Get balance for a specific asset. |
| `get_movements` | `read` | Fetch transaction and movement history with optional filters. |
| `get_user_trades` | `read` | List your own trade fills with optional filters and cursor pagination. |
| `get_funding_payments` | `read` | List your perpetual funding payments with optional filters (trading pair, position, margin account). |

### Fees

| Tool | Profile | Description |
|------|---------|-------------|
| `simulate_fees` | `read` | Simulate fees for an order before placing it. |
| `get_my_fee_tier` | `read` | Get your current fee tier, rolling 14-day volumes, and a pair's fee schedule. |

### Vault

Fund-movement tools require the `full` profile (or an explicit allowlist entry); the allowance and pending-withdrawal reads are available under `read`.

| Tool | Profile | Description |
|------|---------|-------------|
| `vault_approve` | `full` | Approve the vault contract to spend a token. |
| `vault_deposit` | `full` | Deposit tokens into the vault (optional `target`: `spot` default, or `margin` to route into collateral). |
| `vault_withdraw` | `full` | Withdraw tokens from the vault. |
| `vault_get_allowance` | `read` | Check current token allowance for the vault. |
| `vault_needs_approval` | `read` | Check whether an approval transaction is needed before depositing. |
| `get_pending_withdrawals` | `read` | List your pending withdrawals still awaiting on-chain root confirmation. |

### Faucet

Testnet only — the faucet tools are never registered on `mainnet`.

| Tool | Profile | Description |
|------|---------|-------------|
| `request_faucet` | `market-maker` (non-mainnet) | Request test tokens for all trading pairs. |
| `get_faucet_info` | `read` (non-mainnet) | Check remaining faucet quota, next-request time, and recent mint history. |

### Trader codes & rewards

| Tool | Profile | Description |
|------|---------|-------------|
| `get_trader_code_info` | Public | Look up a trader code's details (no credentials required). |
| `check_trader_code_availability` | Public | Public advisory check of whether a custom PitPass TraderCode handle is available (no credentials required). |
| `get_my_trader_code` | `read` | Fetch your own trader code. |
| `set_trader_code` | `market-maker` | Claim or edit your custom (vanity) PitPass TraderCode handle. |
| `clear_trader_code` | `market-maker` | Clear your custom PitPass TraderCode handle, reverting to the wallet-derived default. |
| `get_rewards_balance` | `read` | Fetch your PitPass rewards-bucket balances across reward tokens. |
| `transfer_rewards` | `full` | Move your earned PitPass rewards from the rewards bucket into your own tradeable balance (ledger-only). |

### Market pulse

| Tool | Profile | Description |
|------|---------|-------------|
| `get_pulse` | Public | Get the latest market-pulse news feed: AI-synthesized, per-asset headlines with sentiment tags. |

<!-- END GENERATED TOOLS -->

_This inventory is generated from the tool manifest. Do not edit it by hand — edit
`src/manifest.ts` and run `bun run mcp-docs:gen`._