cTrader MCP Server

This project builds an MCP server for cTrader using the Alpaca reference architecture, adapted to the cTrader API and the bundled OpenApiPy library.

Features

• 16 cTrader tools across account, market, positions, and trading categories

• OpenAPI-first generation using FastMCP from spec-driven sources

• Custom overrides for complex operations (create_order, amend_order, close_position)

• Trust boundary security with parameter validation and account isolation

• Backdoor authentication (no OAuth) using pre-provisioned credentials

• Azure Key Vault integration for credential management

• Comprehensive documentation generation from tool registry

Related MCP server: MetaTrader5 MCP Server

Project Structure

ctrader-mcp-server/
├── src/ctrader_mcp_server/
│   ├── config.py              # Runtime config & Azure Key Vault loading
│   ├── ctrader_session.py     # Backdoor session bootstrap (ProtoOA auth)
│   ├── server.py              # FastMCP server construction with overrides
│   ├── tool_registry.py       # 16 tool definitions with metadata
│   ├── toolsets.py            # Tool organization by category
│   ├── overrides.py           # Custom handlers for complex operations
│   ├── security.py            # Trust boundary & parameter validation
│   ├── readme_docs.py         # Documentation generation
│   └── specs/
│       └── ctrader-api.json   # OpenAPI spec (all 16 endpoints)
├── tests/
│   ├── test_config.py         # Config & Key Vault loading
│   ├── test_ctrader_session.py  # Session bootstrap
│   ├── test_overrides.py      # Override validation logic
│   ├── test_security.py       # Security & trust boundary
│   ├── test_readme_docs.py    # Documentation generation
│   └── test_server_construction.py # Server build & tools
└── OpenApiPy/                 # cTrader client library (submodule)

Available Tools

The server exposes 16 tools organized into 4 categories:

Account (3 tools)

• get_account_status - Current account status and session

• get_trader - Trader profile and account metadata

• get_account_list_by_access_token - Accounts for access token

Market (4 tools)

• list_symbols - Available instruments with metadata

• get_symbol - Detailed symbol information

• list_symbol_categories - Symbol category organization

• get_market_data - Recent market data and quotes

Positions (4 tools)

• list_positions - Open positions and status

• get_position_unrealized_pnl - Position unrealized P&L

• close_position - Close position (with override validation)

• list_deals_by_position_id - Deal history for position

Trading (5 tools)

• list_orders - Open orders with filtering

• get_order_details - Specific order information

• create_order - Create new order (with override validation)

• amend_order - Update order parameters (with override validation)

• cancel_order - Cancel open order

Authentication

The server uses a backdoor authentication model (no OAuth required):

1. Application Auth: ProtoOAApplicationAuthReq with app credentials

2. Account Auth: ProtoOAAccountAuthReq with access token and account ID

3. Session Ready: All subsequent tool requests use authenticated session

from ctrader_mcp_server.config import CTraderRuntimeConfig
from ctrader_mcp_server.ctrader_session import CTraderBackdoorSession

# Load credentials from env or Azure Key Vault
config = CTraderRuntimeConfig.from_env()

# Initialize session with backdoor auth
session = CTraderBackdoorSession(config)

# Session sends auth requests automatically
session.authenticate(client)

Configuration

Environment Variables

export ctrader-app-client-id="your-app-id"
export ctrader-app-client-secret="your-app-secret"
export ctrader-access-token-icmarkets="your-token"
export ctrader-account-id-icmarkets="your-account-id"

Azure Key Vault

Alternatively, set the vault URL:

export AZURE_KEY_VAULT_URL="https://ctrader.vault.azure.net"

The app automatically retrieves:

• ctrader-app-client-id

• ctrader-app-client-secret

• ctrader-access-token-icmarkets

• ctrader-account-id-icmarkets

Security

The server implements trust boundary protection via security.py:

• Account Isolation: Requests always bound to authenticated account

• Parameter Validation: Trading volumes, prices, sides validated

• Output Wrapping: Structured responses wrapped in security envelopes

• Override Validation: Custom functions validate complex requests

Custom Overrides

overrides.py provides targeted handling for complex operations:

# Create order with volume validation
await override_create_order(
    account_id="123",
    symbol="EURUSD",
    side="BUY",
    order_type="MARKET",
    volume=100
)

# Close position with optional partial close
await override_close_position(
    account_id="123",
    position_id="pos-456",
    volume=50  # Optional: partial close
)

# Amend order with price/volume updates
await override_amend_order(
    account_id="123",
    order_id="order-789",
    price=1.2500  # Optional
)

Architecture

• OpenAPI-first MCP generation - Tools derived from spec-driven sources

• FastMCP integration - Mounts spec-generated tools on startup

• Override pattern - Narrow custom handlers for non-trivial endpoints

• Security wrappers - Trust boundary enforcement at request/response boundary

• Aligned with Alpaca reference - Follows established MCP server patterns

Reference Implementation

The Alpaca MCP server provides the architectural blueprint:

• alpaca-mcp-server/README.md

• alpaca-mcp-server/AGENTS.md