Skip to main content

MCP Server Overview

The AEX MCP server (@aex/mcp-server) exposes the AEX market engine as a set of tools consumable by Claude Code and other Model Context Protocol clients. With 38 tools across four categories, you can query live market state, submit and cancel orders, monitor real-time event streams, and drive AI-powered market simulations — all from within a Claude Code session.

The server communicates via stdio transport and connects to your AEX backend over Redis (for state queries) and native WebSocket (for real-time mutations and event streaming).

Prerequisites​

  • Node.js 18+ installed
  • A running AEX backend — the server connects to it at startup
  • Redis accessible from the machine running the MCP server
  • The following environment variables configured (see below)

Environment Variables​

The server reads configuration from environment variables. It also loads AEX/.env automatically if present in the sibling directory.

VariableRequiredDescription
AEX_HOSTYesAEX backend hostname and port (e.g. localhost:8080 or api.dev.pem.aotearoa.energy)
AEX_USER_IDYesAzure AD Object ID of the user to act as. Must be a registered AEX user.
REDIS_HOSTNoRedis host (defaults to localhost)
REDIS_PORTNoRedis port (defaults to 6379)
AEX_BEARER_TOKENNoBearer token for authenticated API calls (production environments)
STRESS_TEST_SECRETNoEnables stress/dev-only tools such as aex_dev_reset_credit_and_docs
STORAGE_TABLE_ENDPOINTNoAzure Table Storage endpoint (required for audit log and order events tools)
STORAGE_ACCOUNT_NAMENoAzure Storage account name
AEX_STORAGE_KEYNoAzure Storage account key
note

AEX_USER_ID must be the Azure AD Object ID of a user already registered in AEX. Mutations are executed as this user, so the user must belong to the correct entity and hold the appropriate permissions. Use aex_list_users to discover registered users.

Connection Model​

The MCP server maintains two independent connections to AEX:

Redis (state client) — used for all query tools. Reads market state, orders, fills, entities, users, products, and credit data directly from Redis. Available immediately on startup, no explicit connection step required.

WebSocket (PubSub client) — used for mutation tools and real-time event monitoring. You must call aex_connect_pubsub before using any mutation tool. Once connected, the server receives a live stream of market events into an in-memory event buffer, which the monitor tools read from.

┌─────────────────────────────────────────┐
│           Claude Code / MCP client      │
└────────────────┬────────────────────────┘
                 │ stdio
┌────────────────▼────────────────────────┐
│            aex-mcp server               │
│                                         │
│  ┌─────────────────┐  ┌──────────────┐  │
│  │  State client   │  │ PubSub client│  │
│  │  (Redis reads)  │  │ (WebSocket)  │  │
│  └────────┬────────┘  └──────┬───────┘  │
└───────────┼──────────────────┼──────────┘
            │                  │
     ┌──────▼──────────────────▼──────┐
     │         AEX backend            │
     │   (Express + Redis + ws)       │
     └────────────────────────────────┘

Tool Categories​

The server exposes 38 tools split into four categories:

Query tools (20 tools)​

Read-only tools that query state from Redis. Safe to call at any time without a WebSocket connection. Includes market state, order book, orders, fills, entities, users, products, credit status, schema discovery, and audit logs.

Mutation tools (10 tools)​

Write operations that send requests to AEX over WebSocket and wait for confirmation. Require aex_connect_pubsub to be called first. Includes order submission and cancellation, market halt/resume, credit limit management, and testing utilities.

Monitor tools (5 tools)​

Read events from the in-memory event buffer populated by the WebSocket connection. Return buffered events with sequence numbers for efficient polling. Includes aex_get_recent_events and per-category watch tools.

Simulation tools (5 tools)​

Control the aex-sim AI market simulator. Start and stop simulations with configurable trading personas, trigger synthetic market events, and query the spot price model.

Quick Start​

The typical workflow is:

1. Verify connectivity

aex_ping
aex_connection_status

2. Explore market state (no connection required)

aex_get_market_state
aex_list_products
aex_list_entities
aex_get_order_book

3. Connect for real-time operations

aex_connect_pubsub

Pass a userId to connect as a specific user, or omit to use AEX_USER_ID from the environment.

4. Submit and monitor orders

aex_create_test_order  { contractId, side, price, quantity }
aex_watch_orders
aex_list_orders        { status: "working" }

5. Clean up

aex_cancel_order       { orderId }
aex_disconnect_pubsub
tip

Use aex_get_module_schema and aex_find_modules for flexible ad-hoc queries across any module type. These tools support operators like gt, lt, contains, and in for precise filtering.

Next Steps​