MCP Tool Reference
Complete reference for all 38 tools exposed by the AEX MCP server, grouped by category. Query tools are read-only and require no WebSocket connection. Mutation tools require you to call aex_connect_pubsub first.
Utility
aex_ping
Test connectivity to the MCP server. Returns server status, version, and a timestamp.
Parameters: none
Returns: { status, server, version, timestamp, toolCount }
aex_connection_status
Report the status of all AEX connections (Redis and WebSocket PubSub). Use this to diagnose connectivity issues or confirm the event buffer is receiving data.
Parameters: none
Returns: { connections: { redis, pubsub }, eventBuffer: { totalEvents, latestSequence, byCategory, oldestEvent, newestEvent } }
Query Tools
Query tools read state from Redis. They are safe to call at any time without a WebSocket connection.
aex_get_market_state
Get the current state of the AEX electricity market.
| Parameter | Type | Required | Description |
|---|---|---|---|
marketId | string | No | Market ID. Defaults to the PEM market. |
Returns: { id, name, code, status, halted, preopen, open, close, currentTime, timezone } where status is one of preopen, open, closed, halted.
aex_get_order_book
Get the bid/ask ladder for a trading contract or engine. Returns the top 5 price levels per side, sorted by price.
| Parameter | Type | Required | Description |
|---|---|---|---|
contractId | string | No | Contract ID to query. |
engineId | string | No | Engine ID (alternative to contractId). |
If neither is provided, returns the book for the first available engine.
Returns: { engineId, contractId, bids, asks, spread, totalWorkingOrders, lastUpdate } where bids and asks are arrays of { price, volume, orderCount }.
aex_get_order
Get details of a specific order by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
orderId | string | Yes | The order ID to retrieve. |
Returns: Full order module data including side, price, quantity, status, and fill information.
aex_list_orders
List orders with optional filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | No | Filter by entity ID. |
status | string | No | Filter by status: working, partial, filled, cancelled, or held. |
limit | number | No | Maximum orders to return (default: 100). |
Returns: { count, orders }
aex_get_fill
Get details of a specific fill (trade execution) by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
fillId | string | Yes | The fill ID to retrieve. |
Returns: Full fill module data including price, quantity, and the related order ID.
aex_list_fills
List trade fills with optional filters.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | No | Filter by entity ID. |
orderId | string | No | Filter by order ID. |
limit | number | No | Maximum fills to return (default: 100). |
Returns: { count, fills }
aex_get_entity
Get details of a specific trading entity.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | The entity ID to retrieve. |
Returns: Entity module data including name, associated users, and credit status.
aex_list_entities
List all trading entities registered in AEX.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Maximum entities to return (default: 100). |
Returns: { count, entities }
aex_get_user
Get details of a specific user.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | The user ID to retrieve. |
Returns: User module data including name, entity assignment, and connection status.
aex_list_users
List users registered in AEX.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | No | Filter by entity ID. |
limit | number | No | Maximum users to return (default: 100). |
Returns: { count, users }
aex_get_product
Get details of a specific trading product.
| Parameter | Type | Required | Description |
|---|---|---|---|
productId | string | Yes | The product ID to retrieve. |
Returns: Product module data including name, type, and contract specifications.
aex_list_products
List all trading products available in AEX.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Maximum products to return (default: 100). |
Returns: { count, products }
aex_get_credit_status
Get the credit status for a trading entity. Requires the connected user to have Credit.View permission and to belong to the same entity (or hold Global scope).
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | The entity ID to query. |
marketId | string | No | Market ID (defaults to PEM). |
Returns: Credit limits, used credit, available credit, and enhanced limit configurations.
aex_get_extended_credit
Get detailed credit data for a specific entity-counterparty relationship. Requires Credit.View permission and matching entity scope.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | The entity ID. |
counterpartyId | string | Yes | The counterparty entity ID. |
Returns: Limit configurations (notional, MW, MWh), usage by type, and documentation status.
aex_list_credit_limit_configs
List all credit limit configurations for an entity across all counterparties. Requires Credit.View permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | The entity ID to query. |
Returns: { entityId, totalConfigs, configs } where each config includes limit type, scope, and value.
aex_get_module_schema
Get the property schema for an AEX module type. Use this to discover which properties are available for filtering with aex_find_modules.
| Parameter | Type | Required | Description |
|---|---|---|---|
moduleType | string | No | One of: ORDER, FILL, USER, ENTITY, PRODUCT, CONTRACT, ENGINE, MARKET, CREDIT, TRADE, QUEUE. Omit to list all types. |
filterableOnly | boolean | No | Return only filterable properties (default: false). |
Returns: Schema with specs and state property definitions, or a list of all module types.
aex_get_module_hierarchy
Get the parent-child relationships between AEX module types and their foreign keys.
| Parameter | Type | Required | Description |
|---|---|---|---|
moduleType | string | No | Module type to inspect. Omit to get the full hierarchy tree. |
Returns: Hierarchy with parent and child relationships, or the full tree.
aex_find_modules
Find modules by type and property filters. Returns matching IDs by default, or full module data when includeData=true.
| Parameter | Type | Required | Description |
|---|---|---|---|
moduleType | string | Yes | Module type to search (same values as aex_get_module_schema). |
filters | object | No | Property filters. Simple: { contractId: "BEN_2501" }. With operator: { price: { value: 15000, operator: "gt" } }. Multiple values: { side: { value: [0, 1], operator: "in" } }. |
limit | number | No | Maximum results (default: 100, max: 1000). |
includeData | boolean | No | Include full module data (default: false, returns IDs only). |
Supported filter operators: eq (default), gt, lt, gte, lte, contains, in.
Returns: { moduleType, total, returned, ids } or { ..., modules } when includeData=true.
Call aex_get_module_schema first to discover which properties support which operators. Attempting to filter on a non-filterable property returns an error.
aex_get_audit_log
Query the AEX audit log stored in Azure Table Storage. Supports relative time expressions for the startTime parameter.
| Parameter | Type | Required | Description |
|---|---|---|---|
moduleType | string | No | Filter by module type (e.g. QUEUE, CREDIT, ENGINE). |
moduleId | string | No | Filter by module instance ID. |
event | string | No | Filter by event name (e.g. orderQueued). |
startTime | string | No | ISO timestamp or relative expression: -1h, -30m, -7d. Filtering is at day granularity. |
endTime | string | No | ISO timestamp (default: now). Day granularity. |
limit | number | No | Max results (default: 50, max: 200). |
search | string | No | Text search within event details. |
Returns: { events, count, hasMore }
Requires STORAGE_TABLE_ENDPOINT, STORAGE_ACCOUNT_NAME, and AEX_STORAGE_KEY to be configured.
aex_get_order_events
Get the full lifecycle event history for an order (submit, modify, cancel, fill, reject, expire) from Azure Table Storage via the AEX backend. Requires Market.Operate permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
orderId | string | Yes | The order ID to retrieve events for. |
date | string | No | Date filter in YYYY-MM-DD format. If omitted, queries the last 7 days. |
Returns: { orderId, count, events, hasMore }
Mutation Tools
Mutation tools modify AEX state over WebSocket. Call aex_connect_pubsub before any mutation tool.
aex_connect_pubsub
Connect to AEX via WebSocket to enable real-time event streaming and mutation confirmation. Once connected, monitor tools will receive live events and mutation tools will wait for confirmations from the backend.
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | No | Azure AD Object ID of the user to connect as. Defaults to AEX_USER_ID from the environment. Use aex_list_users to discover valid user IDs. |
Returns: { status, userId, entityId, capabilities }
aex_disconnect_pubsub
Disconnect from AEX WebSocket. Stops real-time event streaming.
Parameters: none
aex_create_test_order
Create a limit order in AEX via WebSocket. Waits for confirmation from the backend (15 second timeout).
| Parameter | Type | Required | Description |
|---|---|---|---|
contractId | string | Yes | Contract ID to place the order on. |
side | string | Yes | BUY or SELL. |
price | number | Yes | Order price in cents. |
quantity | number | Yes | Order quantity in MW. |
Returns: { status, message, orderId, orderDetails } where status is success, rejected, timeout, not_connected, no_entity, or error.
Orders placed via this tool are real limit orders that participate in matching. Only use against development or test AEX instances.
aex_cancel_order
Cancel an existing order via WebSocket. Waits for confirmation (15 second timeout). Returns not_cancellable if the order is already filled or cancelled.
| Parameter | Type | Required | Description |
|---|---|---|---|
orderId | string | Yes | The order ID to cancel. |
Returns: { status, message, orderId, orderDetails }
aex_halt_market
Halt trading on a market. All order matching pauses immediately. Requires Market.Operate permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
marketId | string | No | Market ID (defaults to PEM market). |
reason | string | No | Reason for the halt (logged by AEX). |
Returns: { status, message, marketId, marketStatus }
aex_resume_market
Resume trading on a halted market. Requires Market.Operate permission.
| Parameter | Type | Required | Description |
|---|---|---|---|
marketId | string | No | Market ID (defaults to PEM market). |
reason | string | No | Reason for resuming (logged by AEX). |
Returns: { status, message, marketId, marketStatus }
aex_set_credit_limit
Set or update a credit limit for a trading entity pair. Supports multiple limit types and scopes. The connected user must belong to entityId.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | Entity ID setting the limit (must match the connected user's entity). |
counterpartyId | string | Yes | Counterparty entity ID the limit applies to. |
limitType | string | Yes | notional (dollar value), mw (megawatts), or mwh (megawatt-hours). |
scope | string | Yes | total (single limit for all contracts) or per_contract (separate limits per contract). |
limit | number | Yes | Credit limit value. |
marginPercent | number | No | Margin percentage (0–100) applied to face value. |
contractId | string | No | Required when scope is per_contract. |
Returns: { status, message, result }
aex_set_documentation_status
Set ISDA documentation status for a counterparty relationship. Both parties must mark docs_in_place before trading is allowed. The connected user must belong to entityId.
| Parameter | Type | Required | Description |
|---|---|---|---|
entityId | string | Yes | Entity ID setting the status (must match the connected user's entity). |
counterpartyId | string | Yes | Counterparty entity ID. |
status | string | Yes | docs_in_place, no_docs, or pending. |
notes | string | No | Optional notes about the documentation. |
Returns: { status, message, result }
aex_flush_order_book
Cancel all open orders in a specific order book engine. Testing only. Requires Market.Operate permission and confirm=true.
| Parameter | Type | Required | Description |
|---|---|---|---|
engineId | string | No | Engine ID to flush. Defaults to the first engine. |
contractId | string | No | Contract ID to flush (alternative to engineId). |
confirm | boolean | No | Must be true to execute. Omit to preview the number of orders affected. |
Returns: { status, message, engineId, contractId, ordersAffected }
This permanently cancels all open orders in the specified book. Use only in development or testing environments.
aex_flush_all_orders
Cancel all orders across all entities and clear fill history. Operator-only. Requires Market.Operate permission and confirm=true.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirm | boolean | No | Must be true to execute. Omit to preview the count of orders affected. |
Returns: { status, message, ordersAffected }
This is a destructive operation that affects all trading entities. Use only in development or testing environments.
aex_dev_reset_credit_and_docs
Bulk-set all credit limits between all entity pairs to a given value and mark all documentation statuses as docs_in_place. Only available when STRESS_TEST_SECRET is configured. Idempotent — safe to run multiple times.
| Parameter | Type | Required | Description |
|---|---|---|---|
creditLimit | number | Yes | Notional credit limit value to set for every entity pair. |
skipCredit | boolean | No | Skip credit limit updates (only set documentation). |
skipDocs | boolean | No | Skip documentation updates (only set credit limits). |
Returns: { status, message, summary: { entities, pairs, creditUpdates, docsUpdates }, errors }
Monitor Tools
Monitor tools read from an in-memory event buffer populated by the WebSocket connection. Call aex_connect_pubsub to start receiving events. Use the since parameter with the latestSequence from the previous response to poll incrementally for new events.
aex_get_recent_events
Get recent events from the buffer across all or a specific category.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | order, fill, pricing, market, credit, system, other, or all (default). |
limit | number | No | Maximum events to return (default: 50). |
since | number | No | Only return events after this sequence number. |
eventTypes | string[] | No | Filter by specific event type strings (e.g. ["new.order", "change.order"]). |
Returns: { events, count, stats: { totalBuffered, latestSequence, byCategory }, filters }
aex_watch_orders
Get recent order events (new orders, modifications, cancellations).
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Maximum events to return (default: 50). |
since | number | No | Only return events after this sequence number. |
orderTypes | string[] | No | Filter by order event types. |
Returns: { events, count, latestSequence, totalOrderEvents, filters }
aex_watch_fills
Get recent fill and trade execution events.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Maximum events to return (default: 50). |
since | number | No | Only return events after this sequence number. |
fillTypes | string[] | No | Filter by fill event types. |
Returns: { events, count, latestSequence, totalFillEvents, filters }
aex_watch_book
Get recent order book and pricing change events.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Maximum events to return (default: 50). |
since | number | No | Only return events after this sequence number. |
productCode | string | No | Filter by product code. |
Returns: { events, count, latestSequence, totalPricingEvents, filters }
aex_watch_market
Get recent market state change events (session changes, halts, status updates).
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Maximum events to return (default: 50). |
since | number | No | Only return events after this sequence number. |
Returns: { events, count, latestSequence, totalMarketEvents, filters }
Simulation Tools
Simulation tools control the aex-sim AI market simulator. See Market Simulation for full details and usage examples.
aex_sim_start
Start the market simulation with one or more AI trading personas.
aex_sim_stop
Stop the running simulation. Cancels all outstanding orders and disconnects all personas.
aex_sim_status
Get the current simulation status including persona positions, order counts, and aggregate metrics.
aex_sim_get_spot_prices
Get current simulated spot prices for BEN and OTA nodes, including regime state and active market events.
aex_sim_trigger_event
Manually inject a market event into the spot price simulation.
See Market Simulation for full parameter details on all simulation tools.
Next Steps
- Market Simulation — full reference for simulation tools and persona configuration