Skip to main content

​
Monaco Protocol SDK v1.0.33

This release scopes the MCP server behind capability profiles — a breaking change for authenticated MCP sessions — adds 36 MCP tools spanning perps, positions, portfolio, margin accounts, and related account/market data, and makes batch order replacement cancel-first across the TypeScript, Rust REST, and Rust gRPC clients. It also fixes Retry-After parsing on APIError and the request_faucet MCP tool, and corrects stale JWT references in client JSDoc. The MCP capability default is the one action item worth reviewing before you upgrade.

​
Breaking: authenticated MCP sessions are scoped by a capability profile

Authenticated MCP sessions are now bounded by MONACO_CAPABILITY (read | market-maker | full, default read). Supplying a private key no longer unlocks the entire authenticated tool set: by default a key grants read-only tools, order placement/cancel/replace require market-maker, and fund-movement or privilege tools (vault approve/deposit/withdraw and transfer_rewards) require full or an explicit MONACO_TOOL_ALLOWLIST entry. MONACO_NETWORK is now required whenever a private key is configured — the server no longer silently defaults an authenticated session to mainnet. New MONACO_TOOL_ALLOWLIST and MONACO_TOOL_DENYLIST variables give per-tool overrides, with the denylist winning over both the profile and the allowlist. See Capability profiles for the full policy.

​
Added

​
36 new MCP tools

The MCP server adds 36 tools covering perps, positions, portfolio, margin accounts, and related account/market data that were previously absent from the MCP surface:
  • Perp market data — get_perp_market_config, get_perp_market_summary, get_mark_price, get_index_price, get_funding_state, get_open_interest, get_funding_history, get_all_funding_history
  • Market — get_screener, get_market_stats
  • Positions — get_positions, get_position, get_position_risk, get_position_history, get_position_pnl_history
  • Portfolio — get_portfolio_summary, get_portfolio_performance, get_portfolio_realized_pnl, get_portfolio_assets, get_portfolio_margin
  • Margin accounts — get_margin_accounts, get_parent_margin_account_summary, get_available_collateral, get_parent_margin_account_movements, and the simulate_parent_margin_order_risk / simulate_risk_bucket_order_risk risk previews
  • Account & market data — get_user_trades, get_funding_payments, get_pending_withdrawals, and the public get_pulse news feed
All of these are read tools under the default read profile, except close_position (which requires market-maker) and the collateral-movement tools (add_position_margin, reduce_position_margin, and the parent- and risk-bucket transfers), which are fund-movement and require full. The @deprecated per-margin-account forms are intentionally not exposed; their non-deprecated parent/risk-bucket equivalents are. Tool input/output schemas mirror the SDK’s camelCase ergonomic types and cross-field refinements. See the full MCP tool list.

​
Changed

​
Batch order replacement is cancel-first

sdk.trading.batchReplace / batchReplaceMarginLimitOrders — and the Rust REST/gRPC batch_replace_orders — are now cancel-first: the matching engine cancels every item’s original before placing any replacement, in request order. A two-sided quote can shift across its own resting prices in one call without tripping self-trade prevention, and a replacement may lock funds freed by any original in the batch. Failure semantics changed with it. An item whose replacement fails to place (insufficient balance, self-trade against an order outside the batch, risk rejection) now reports the error with its original already cancelled — previously a failed item left its original resting. Items that fail validation, or whose original cannot be found, still leave the original untouched.

​
MCP tool inventory generated from a manifest

The tool inventory in the MCP README is now generated from a single deterministic manifest (src/manifest.ts) that classifies every tool by category, auth mode, capability profile, network restriction, and side effect. The capability policy and the test profile buckets derive from this manifest, and a CI drift gate fails if the documented tool set diverges from the tools the server actually registers. No tool behavior changed.

​
Fixed

​
Retry-After HTTP-date parsing on APIError

APIError.retryAfter now also parses the HTTP-date form of the Retry-After response header, converting it to the remaining delay in seconds (past dates clamp to 0); previously an HTTP-date was dropped. All three RFC 7231 HTTP-date formats are accepted (IMF-fixdate, RFC 850, and asctime), timestamps are built as UTC, and impossible calendar dates (e.g. 31 Feb) or malformed values are ignored rather than coerced into a bogus delay. The numeric form is unchanged. The value is in seconds — multiply by 1000 before passing it to setTimeout. See error handling.

​
request_faucet MCP tool

The request_faucet MCP tool was dead: it referenced the removed accessToken auth wiring and always failed with “No access token available”. It now calls the current faucet SDK path (sdk.faucet.mint) and takes the required Cloudflare Turnstile turnstileToken input. The tool remains network-restricted and is never registered on mainnet.

​
Session-key auth documented in client JSDoc

The WebSocket client (subscribeUserOrders, subscribeBalances, subscribeMovements, sendAuthenticate), the React hooks (useUserBalances, useUserMovements, useUserOrders), and the WebSocket balance/movement event types no longer reference JWT/token authentication in their JSDoc. They now document that the user is identified from the signed session-key Authenticate handshake over WS-AUTH\n<public_key>\n<timestamp>, matching the tokenless v0.8.8 model, and that the handshake timestamp is bound into the signature and validated within a ±30s skew window (re-signed on every reconnect). Behavior and signatures are unchanged; these are documentation-only corrections.

​
Upgrade

The MCP server ships at 1.0.33 too; it runs via npx -y @0xmonaco/mcp-server, so a restart of your assistant picks up the new version and the capability-profile behavior below. Action items to review:
  1. Authenticated MCP sessions default to read-only. After upgrading, an authenticated MCP server started without MONACO_CAPABILITY exposes read tools only — set MONACO_CAPABILITY=market-maker to place, cancel, and replace orders, or full for vault fund movement. MONACO_NETWORK is now required whenever a private key is set; the server no longer defaults to mainnet.
  2. Batch replace is cancel-first. A replacement that fails to place now leaves its original already cancelled, not resting. Re-check any batch-replace error handling that assumed a failed item kept its original order live.
  3. Retry-After is in seconds. APIError.retryAfter is delay-seconds (now also derived from HTTP-date headers); multiply by 1000 before passing it to setTimeout.