Orderly MCP

Orderly Network MCP Server

A Model Context Protocol (MCP) server providing documentation and SDK patterns for Orderly Network - an omnichain perpetual futures trading infrastructure.

Quick Start

Install the MCP server with one command for your AI client:

npx @orderly.network/mcp-server init --client <client>

Supported clients: claude, cursor, vscode, codex, opencode

Examples

# OpenCode

npx @orderly.network/mcp-server init --client opencode

Claude Code

npx @orderly.network/mcp-server init --client claude

Cursor

npx @orderly.network/mcp-server init --client cursor

VS Code (with Copilot)

npx @orderly.network/mcp-server init --client vscode

Interactive mode (prompts for client selection)

npx @orderly.network/mcp-server init

This command will:

1. Create the appropriate configuration file for your AI client
2. Install @orderly.network/mcp-server as a dev dependency
3. Guide you through the next steps

After installation: Restart your AI client and try asking: _"How do I connect to Orderly Network?"_

---

What This Server Provides

This MCP server enables AI assistants to answer questions about Orderly Network and guide developers in building React components using the Orderly SDK v2.

Features

• Documentation Search: Query Orderly docs for architecture, APIs, and concepts
• SDK Patterns: Get code examples for all v2 hooks (useOrderEntry, usePositionStream, etc.)
• Contract Addresses: Lookup smart contract addresses for all supported chains
• Workflow Guides: Step-by-step explanations of common development tasks
• Component Guides: Patterns for building trading UI components
• API Reference: REST and WebSocket endpoint documentation
• Indexer API: Trading metrics, account events, trades, and volume statistics
• Orderly Predict: 5-minute BTC Up/Down rounds, order rules, settlement, fees, and SDK integration (covered by documentation search)

Installation

Quick Install (Recommended)

Use the CLI to automatically configure your AI client:

npx @orderly.network/mcp-server init --client <client>

Available clients:

Manual Setup

If you prefer to configure manually or the automatic setup doesn't work for your client:

Prerequisites

• Node.js 18 or higher
• Yarn (or npm)

Setup from Source

1. Clone or create the project:

cd orderly-mcp

1. Install dependencies:

yarn install

1. Build the project:

yarn build

Hosted Server

A publicly hosted instance is available at `https://mcp.orderly.network`.

Health check:

curl https://mcp.orderly.network/health

Use in MCP client config (Streamable HTTP):

{

"mcpServers": { "orderly": { "url": "https://mcp.orderly.network/" } } }

Running the Server

The MCP server supports two modes:

1. Stdio Mode (Default - for local MCP clients)

Use this for local AI assistants:

yarn start

Manual Configuration

If not using the automatic installer, add this configuration to your AI client:

Claude Code (.mcp.json):

{

"mcpServers": { "orderly": { "command": "npx", "args": ["@orderly.network/mcp-server@latest"] } } }

Cursor (.cursor/mcp.json):

{

"mcpServers": { "orderly": { "command": "npx", "args": ["@orderly.network/mcp-server@latest"] } } }

VS Code (.vscode/mcp.json):

{

"servers": { "orderly": { "command": "npx", "args": ["@orderly.network/mcp-server@latest"] } } }

OpenCode (.opencode/mcp.json):

{

"$schema": "https://opencode.ai/config.json", "mcp": { "orderly": { "type": "local", "command": ["npx", "@orderly.network/mcp-server@latest"], "enabled": true } } }

Codex (~/.codex/config.toml):

[mcp_servers.orderly]

command = "npx" args = ["@orderly.network/mcp-server@latest"]

2. HTTP Mode (for self-hosted deployments)

Run as an HTTP server for remote access:

yarn start:http

The server will start on port 3000 (or PORT env var):

• MCP endpoint: http://localhost:3000/
• Health check: http://localhost:3000/health

Note: A public instance is already deployed at https://mcp.orderly.network - see Hosted Server above.

Docker Deployment:

# Build the image

docker build -t orderly-mcp .

Run the container

docker run -p 3000:3000 orderly-mcp

The Docker image runs in stateless HTTP mode by default.

Development

For development with auto-rebuild:

yarn dev

Code Quality

This project uses ESLint and Prettier for code quality:

# Run linting

yarn lint

Fix linting issues

yarn lint:fix

Format code

yarn format

Check formatting

yarn format:check

Type check

yarn typecheck

Available Tools

1. search_orderly_docs

Search Orderly documentation for specific topics, concepts, or questions.

Parameters:

• query (string, required): Search query about Orderly
• limit (number, optional): Maximum results (default: 5)

Example queries:

• "how does the vault work"
• "trading fees"
• "order types"
• "leverage calculation"

SDK symbols (hooks, types, components, functions) are now surfaced inline by

search_orderly_docs — see SDK symbol search below.

2. get_contract_addresses

Get smart contract addresses for Orderly on specific chains.

Parameters:

• chain (string, required): Chain name (e.g., 'arbitrum', 'optimism', 'base')
• contractType (string, optional): Contract type or 'all' (default: 'all')
• network (string, optional): 'mainnet' or 'testnet' (default: 'mainnet')

Supported chains:

• EVM: ethereum, arbitrum, optimism, base, mantle, solana
• Orderly L2: orderlyL2

3. explain_workflow

Get step-by-step explanation of common development workflows.

Parameters:

• workflow (string, required): Workflow name

Available workflows:

• wallet connection: Connect wallet and create an Orderly key
• place first order / limit order: Create, track, edit, and cancel an order
• deposit: Approve and deposit through the Vault contract
• withdraw: Sign the EIP-712 withdrawal and submit it
• set tp sl: Create bracket take-profit/stop-loss orders

4. get_api_info

Get information about Orderly REST API or WebSocket streams.

Parameters:

• type (string, required): 'rest', 'websocket', or 'auth'
• endpoint (string, optional): Specific endpoint or stream name

5. get_indexer_api_info

Get information about Orderly Indexer API for trading metrics, account events, trades, and volume statistics (rankings endpoints available via endpoint search).

Parameters:

• endpoint (string, optional): Specific endpoint path or name (e.g., '/events_v2', 'daily_volume', 'ranking/positions')
• category (string, optional): Filter by category (e.g., 'trading_metrics', 'events::events_api', 'trades::trades_api')

Available categories:

• Trading Metrics: Daily volume, fees, perp trading data (/daily_volume, /daily_trading_fee, /daily_orderly_perp)
• Events: Account events with pagination (/events_v2) - trades, settlements, liquidations, transactions
• Volume Statistics: Account and broker volume stats (/get_account_volume_statistic, /get_broker_volume_statistic)
• Trades: Trade data with filters (/trades)

Rankings (no category; search by endpoint):

• Positions, PnL, trading volume, deposits/withdrawals (/ranking/positions, /ranking/realized_pnl, /ranking/trading_volume, /ranking/deposit, /ranking/withdraw)

Example:

# Get all indexer API endpoints

get_indexer_api_info

Get specific endpoint details

get_indexer_api_info endpoint="/events_v2"

Get all endpoints in a category

get_indexer_api_info category="trading_metrics"

6. get_component_guide

Get guidance on building React UI components using Orderly SDK.

Parameters:

• component (string, required): Component type
• complexity (string, optional): 'minimal', 'standard', or 'advanced' (default: 'standard')

Available guides: TradingPage, OrderBook, OrderEntryWidget, OrderEntry, PositionsWidget, WalletConnectorWidget.

Other components return a pointer to search_orderly_docs (scope sdk).

7. get_orderly_one_api_info

Get information about Orderly One API for DEX creation, graduation, and management.

Parameters:

• endpoint (string, optional): Specific endpoint path or name (e.g., '/dex', 'verify-tx', '/theme/modify')
• category (string, optional): Filter by category (e.g., 'auth', 'dex', 'graduation', 'theme', 'stats', 'leaderboard', 'admin')

Available categories:

• auth: Wallet signature-based authentication (nonce, verify, validate)
• dex: DEX management - create, update, delete, deploy, and manage exchanges
• graduation: Graduation system - upgrade from demo to full broker with fee splits
• theme: AI-powered theme generation and CSS customization
• stats: Platform-wide statistics and analytics
• leaderboard: DEX rankings, performance metrics, and leaderboards
• admin: Administrative operations for platform management

Example:

# Get overview and authentication flow

get_orderly_one_api_info

Get all endpoints in a category

get_orderly_one_api_info category="dex" get_orderly_one_api_info category="graduation"

Get specific endpoint details

get_orderly_one_api_info endpoint="verify-tx" get_orderly_one_api_info endpoint="/theme/modify"

Available Resources

Access comprehensive documentation via resource URIs. All resources support fuzzy search with pagination:

Query Parameters:

• search (required) - Fuzzy search query
• page (optional) - Page number (default: 1)
• limit (optional) - Results per page, max 10 (default: 10)

Resources:

• orderly://overview - High-level protocol architecture (no search required)
• orderly://sdk/hooks?search=orderEntry - Search SDK hooks by name, description, or category
• orderly://sdk/components?search=Checkbox - Search components by name or description
• orderly://contracts?search=arbitrum - Search contracts by chain or name
• orderly://workflows?search=wallet - Search workflows by name or steps
• orderly://api/rest?search=position - Search REST API endpoints
• orderly://api/websocket?search=orderbook - Search WebSocket streams
• orderly://api/indexer?search=events - Search Indexer API endpoints

Example:

orderly://sdk/hooks?search=useOrderEntry&page=1&limit=5

Example Usage

Searching Documentation

User: "How does Orderly's vault system work?"

AI uses search_orderly_docs with query "vault system" → Returns explanation of cross-chain vault architecture

Searching SDK Symbols

User: "Show me how to use useOrderEntry"

AI uses search_orderly_docs with query "useOrderEntry" → Returns inline SDK hook record: signature, params, returns, source path

Looking Up Contracts

User: "What's the USDC address on Arbitrum?"

AI uses get_contract_addresses with chain "arbitrum", contractType "USDC" → Returns contract address

Explaining Workflows

User: "How do I place my first order?"

AI uses explain_workflow with workflow "place first order" → Returns step-by-step guide

Component Building Guide

User: "How do I build