@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 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. | | 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) |

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.

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.

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

{
  "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 — the profile column shows the minimum profile each tool needs.

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. Not idempotent — after an ambiguous failure (timeout/network error/5xx with no order), reconcile with get_orders/get_order before retrying; never blind-retry. | | 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. Not idempotent — after an ambiguous failure (timeout/network error/5xx with no order), reconcile with get_orders/get_order before retrying; never blind-retry. | | replace_order | market-maker | Modify an existing order's price and/or quantity. Not idempotent — after an ambiguous failure (timeout/network error/5xx with no order), reconcile with get_order before retrying; never blind-retry. | | 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. | | add_position_margin | full | Add isolated margin collateral to a perpetual position. | | reduce_position_margin | full | Withdraw isolated margin collateral from a perpetual position back to the account. |

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. |

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.