MCP Server

Monaco is built to be driven by AI. Paste the config below into your assistant to expose Monaco’s market data and trading as callable MCP tools — no code required. Two modes are available:

Public mode — no credentials; read-only market data, orderbook, and trades are available immediately.
Authenticated mode — add your wallet private key, client ID, and network to enable authenticated tools. Which tools are enabled is bounded by a capability profile: supplying a key does not blindly unlock everything. The default profile is read-only; trading requires opting in to market-maker, and fund movement (deposits, withdrawals, reward transfers) requires full.

The MCP server is a command and snapshot plane: it places, replaces, and cancels orders and takes one-shot reads (get_orders, get_positions, get_balances, get_orderbook). It has no streaming or subscription tools — every read is a point-in-time snapshot. For live fills, cancels, book movement, and position/risk changes, pair it with the Core SDK WebSocket state plane. If you are running a market maker or any continuously-managed strategy, follow the Market-Maker Runbook.

Add the MCP server

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

claude mcp add monaco \
  -e MONACO_NETWORK=staging \
  -- npx -y @0xmonaco/mcp-server

# ~/.codex/config.toml
[mcp_servers.monaco]
command = "npx"
args = ["-y", "@0xmonaco/mcp-server"]
env = { MONACO_NETWORK = "staging" }

That’s the public, read-only server — live market data, orderbook, and trades with zero credentials. Restart your assistant after editing a config file. To enable authenticated tools, add your wallet private key, client ID, and network. By default this grants read-only access (balances, orders, fee tier); set MONACO_CAPABILITY=market-maker to place and cancel orders, and MONACO_CAPABILITY=full for vault fund movement. Full per-client setup, authenticated config, capability profiles, and the complete tool list are below.

Point your AI at the docs

These docs are LLM-readable, so any model or agent can ingest them directly:

File	What it is
`/llms.txt`	A structured index of every page — point an agent here to let it crawl on demand.
`/llms-full.txt`	The entire documentation as one plain-text file — paste it straight into a model’s context.

Every page also has Copy page and Open in ChatGPT / Claude buttons in the top-right, and appending .md to any docs URL returns the raw Markdown.

Drive Monaco in natural language

Once the MCP server is connected, just ask:

What’s the current ETH/USDC orderbook on Monaco, and how does the mid price compare to the last few trades?

In authenticated mode the agent can place and cancel real orders. Start on staging (testnet) and review what it proposes before confirming trades.

Trading with MCP

Authenticated mode lets an MCP-compatible assistant act through the wallet configured by MONACO_PRIVATE_KEY, within the bounds of the active capability profile. The default read profile lets the agent inspect balances, open orders, and fees only. Set MONACO_CAPABILITY=market-maker to let it request testnet funds, place spot or perp orders, replace orders, and cancel orders. Moving funds through the Monaco vault tools (deposit, withdraw) and transferring rewards require the full profile — they are off unless explicitly enabled. Use this mode when you want an assistant to operate Monaco directly from natural language, for example:

“Check my balances, then place a small ETH/USDC limit buy 5% below mid.”
“Cancel my stale open orders before placing a new quote.”
“Simulate fees for this order before submitting it.”

MCP is not a standalone market-making surface. Because it does not stream, an agent that manages quotes off intermittent MCP snapshots alone will miss fills, cancels, and book movement between calls — leaving stale quotes and one-sided exposure. Drive commands through MCP, but track live state through the Core SDK WebSocket. See the Market-Maker Runbook for the full command-plane vs state-plane loop.

Authenticated MCP tools control the configured wallet on the selected network. Use staging first, keep private keys out of committed config files, and review trading actions before approving them.

Capability profiles

Authenticated mode is scoped by MONACO_CAPABILITY. The profile bounds which tools the server registers — a tool outside the active profile (and not named in MONACO_TOOL_ALLOWLIST) is never registered. This is an authorization control, not an advisory annotation.

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

The default read profile cannot mutate anything — order placement, cancel, replace, and close require MONACO_CAPABILITY=market-maker or higher. Fund-movement and privilege tools additionally require full; enable them by setting MONACO_CAPABILITY=full, or opt a single tool in with MONACO_TOOL_ALLOWLIST (e.g. MONACO_TOOL_ALLOWLIST=vault_withdraw). MONACO_TOOL_DENYLIST removes tools and wins over both the profile and the allowlist. Also note: when a private key is configured, MONACO_NETWORK is required — the server refuses to default an authenticated session to mainnet.

Grant the full profile only when you intend an agent to move funds, and prefer a per-tool MONACO_TOOL_ALLOWLIST over blanket full — especially on mainnet.

Delegated owner mode

Set MONACO_DELEGATED_OWNER_USER_ID to run the server 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.

"env": {
  "MONACO_NETWORK": "staging",
  "MONACO_PRIVATE_KEY": "0x...",
  "MONACO_CLIENT_ID": "your-client-id",
  "MONACO_CAPABILITY": "market-maker",
  "MONACO_DELEGATED_OWNER_USER_ID": "the-owner-user-id"
}

This is fail-closed: MONACO_DELEGATED_OWNER_USER_ID requires MONACO_PRIVATE_KEY and MONACO_CLIENT_ID (the agent must authenticate as itself first), a blank value is rejected, and if owner adoption fails the server does not silently fall back to trading as the agent’s own account. The delegated session inherits withdrawal restrictions from the policy — 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.

IDE setup

Follow the setup instructions below for your client. Some clients use an MCP config file; Claude Code can be configured via the CLI.

Claude Code (CLI)
Claude Desktop (macOS)
Claude Desktop (Windows)
Cursor
Windsurf

Claude Code registers MCP servers from the command line — no config file to edit.Public mode:

claude mcp add monaco \
  -e MONACO_NETWORK=staging \
  -- npx -y @0xmonaco/mcp-server

Authenticated mode: For security, avoid pasting MONACO_PRIVATE_KEY into your shell history; prefer a secret manager or environment variable.

claude mcp add monaco \
  -e MONACO_NETWORK=staging \
  -e MONACO_PRIVATE_KEY=0x... \
  -e MONACO_CLIENT_ID=your-client-id \
  -- npx -y @0xmonaco/mcp-server

Verify it registered with claude mcp list, then start a session with claude.

Config file: ~/Library/Application Support/Claude/claude_desktop_config.jsonPublic mode:

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

Authenticated mode:

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

Config file: %APPDATA%\Claude\claude_desktop_config.jsonPublic mode:

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

Authenticated mode:

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

Config file: ~/.cursor/mcp.jsonPublic mode:

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

Authenticated mode:

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

Config file: ~/.codeium/windsurf/mcp_config.jsonPublic mode:

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

Authenticated mode:

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

After editing the config file, restart your AI assistant.

Never commit your MCP config file to version control. MONACO_PRIVATE_KEY is a raw private key — anyone with access to it controls your wallet.

Configuration

string

Network to connect to (mainnet, development, staging, local). Set to staging for testnet. Required when MONACO_PRIVATE_KEY is set — the server refuses to default an authenticated session to mainnet. Public-only mode defaults to mainnet.

string

Your wallet’s private key in 0x... format. Required for authenticated tools. If omitted, only public tools are available.

string

Your Monaco application client ID. Required when MONACO_PRIVATE_KEY is set. Contact [email protected] to obtain one.

string

default:"read"

Capability profile for authenticated mode: read, market-maker, or full. See capability profiles. Defaults to read (no write authority); market-maker adds order management, and full adds fund movement.

string

Comma-separated tool names to enable on top of the active profile — an explicit per-tool opt-in, including for full-only fund-movement tools (e.g. vault_withdraw).

string

Comma-separated tool names to disable. Wins over both the profile and the allowlist.

string

Sei RPC endpoint URL. Defaults to https://evm-rpc-testnet.sei-apis.com when MONACO_NETWORK=staging. The default is a public testnet RPC — rate limits may vary and it is not suitable for production. Override with a dedicated private RPC provider for better reliability.

string

Run the server on behalf of a delegated owner account instead of the configured wallet’s own account. The MONACO_PRIVATE_KEY wallet is the agent: on startup it authenticates as itself, then adopts an owner-scoped session (loginAsDelegatedOwner) so every tool call acts on the owner, with the agent wallet preserved as the audit actor. Fail-closed — requires MONACO_PRIVATE_KEY and MONACO_CLIENT_ID, rejects a blank value, and never falls back to trading as the agent’s own account. See delegated owner mode.

Available 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 below 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. 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.
`transfer_collateral_to_sub_account`	`full`	Move collateral from your default (parent) margin account into one of your margin sub-accounts.
`transfer_collateral_from_sub_account`	`full`	Move collateral from one of your margin sub-accounts back to your default (parent) margin account.

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

Copy trading

The leaderboard, leader profiles and closed trades are public. Your own reads are available under read; registering as a leader and stopping a follow require market-maker; following (which moves the allocation into a copy account) and adding margin to a copy position (which moves copy account collateral into the position) require full.

Tool	Profile	Description
`list_lead_traders`	Public	Public copy trading leaderboard: lead traders ranked by ROI, PnL, followers, allocated AUM, marked AUM or win rate over a stats window (no credentials required).
`get_lead_trader`	Public	Public profile, follow summary and stats of one lead trader, by custom TraderCode handle (no credentials required).
`list_lead_trader_closed_trades`	Public	Public list of a lead trader’s closed trades, newest first (no credentials required).
`list_lead_trader_open_positions`	`read`	Open positions of a lead trader you currently follow (followers only).
`get_my_lead_trader`	`read`	Fetch your own lead trader profile, follow summary and stats.
`list_my_followers`	`read`	List your followers, as a lead trader.
`list_my_follows`	`read`	List your copy trading follows and their settings.
`get_follow`	`read`	Fetch one of your follows with its most recent skipped mirrors and its copy account’s marked equity.
`preview_follow`	`read`	Preview what following a lead trader with copyExisting would open: estimated margin and fees and how many positions would be copied (read-only).
`list_follow_leader_positions`	`read`	Open positions of the lead trader one of your follows copies (live follows only).
`upsert_lead_trader`	`market-maker`	Register as a lead trader, or edit your lead profile (profit share, bio, status, minimum allocation).
`upsert_follow`	`full`	Follow a lead trader (moves the allocation into a new copy account) or edit one of your follows.
`stop_follow`	`market-maker`	Stop one of your follows: the leader’s fills stop being mirrored.
`close_follow_positions`	`market-maker`	Close one follow’s copy positions at market and keep the follow (it keeps mirroring).
`close_all_copy_positions`	`market-maker`	Close the copy positions of all your follows at market and keep the follows.
`add_follow_position_margin`	`full`	Add margin to one of your copy positions from the follow’s copy account (lowers its leverage; your margin account is never touched; no reduction). Not idempotent — after a timeout, read the follow before retrying, or the amount may be added twice.

Market pulse

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

Example prompts

Once the server is connected, drive Monaco entirely in natural language. Your AI assistant picks the right tools and chains them together. Public — no credentials needed:

What’s the current ETH/USDC orderbook on Monaco, and how does the mid price compare to the last few trades?

Pull the last 24 hours of hourly candlesticks for BTC/USDC and summarize the trend.

Authenticated — requires MONACO_PRIVATE_KEY, MONACO_CLIENT_ID, and MONACO_NETWORK (and MONACO_CAPABILITY=market-maker to place orders):

Request test tokens from the faucet, then place a limit buy for 0.1 ETH/USDC at 5% below the current mid price.

Check my open orders and balances, then cancel any resting buy orders older than I’d expect to still be unfilled.

Simulate the fees for a 1 ETH/USDC market sell before I place it.

In authenticated mode the agent can place and cancel real orders on the configured network. Start on staging (testnet) and review what the agent proposes before confirming trades.

Learn

Build

Libraries

APIs

Resources

Add the MCP server

Point your AI at the docs

Drive Monaco in natural language

Trading with MCP

Capability profiles

Delegated owner mode

IDE setup

Configuration

Available tools

Search

Market

Perp market data

Orderbook

Trades

Trading

Positions

Portfolio

Margin accounts

Profile

Fees

Vault

Faucet

Trader codes & rewards

Copy trading

Market pulse

Example prompts

​Add the MCP server

​Point your AI at the docs

​Drive Monaco in natural language

​Trading with MCP

​Capability profiles

​Delegated owner mode

​IDE setup

​Configuration

​Available tools

​Search

​Market

​Perp market data

​Orderbook

​Trades

​Trading

​Positions

​Portfolio

​Margin accounts

​Profile

​Fees

​Vault

​Faucet

​Trader codes & rewards

​Copy trading

​Market pulse

​Example prompts

Add the MCP server

Point your AI at the docs

Drive Monaco in natural language

Trading with MCP

Capability profiles

Delegated owner mode

IDE setup

Configuration

Available tools

Search

Market

Perp market data

Orderbook

Trades

Trading

Positions

Portfolio

Margin accounts

Profile

Fees

Vault

Faucet

Trader codes & rewards

Copy trading

Market pulse

Example prompts