Aleatoric MCP Client

Official MCP client SDK for Aleatoric Systems — Institutional-grade synthetic market data generation.

Verified Compliance: This client is fully compliant with Aleatoric Engine API v0.5.10 and MCP Protocol Version 2024-11-05 (JSON-RPC 2.0). All examples are tested against live production endpoints.

Keywords: mcp market-data synthetic-data backtesting trading fintech quantitative-finance perpetuals futures order-book

Overview

Aleatoric MCP provides AI assistants with tools to generate deterministic synthetic market data for backtesting, stress testing, and model validation. Connect your AI coding assistant to generate reproducible datasets across 6 major exchanges.

See our Roadmap for planned features and architectural updates.

Supported Exchanges: Binance, HyperLiquid, OKX, Bybit, CME, SGX

⚡ 90-Second Demo

Run this in your AI assistant (Cursor, Claude, Windsurf):

"Generate a 1-hour dataset of BTC/USDT L2 order book updates on Binance. Use seed 123 for reproducibility. Plot the mid-price and spread over time."

What happens:

Agent calls generate_dataset to request the data.
Server generates 3,600s of data (approx 14,000 events) with realistic microstructure.
Agent receives a signed download URL.
Agent plots the exact price path defined by seed=123.

Result: A fully reproducible market scenario for your backtest in under 2 minutes.

Public Validation Showcase

Run a deterministic hash check and optional Parquet export against the hosted MCP without any local server:

cd public/aleatoric-engine-mcp
pip install -r examples/requirements.txt
export ALEATORIC_API_KEY="your-api-key"
python examples/validation_showcase.py --symbol BTC --seed 42 --duration 60

If you have a cache key, add --cache-key <key> to download a Parquet artifact.

Use Cases

Backtesting — Generate months of realistic order book data in seconds
Stress Testing — Simulate extreme market conditions with reproducible seeds
Model Validation — Test trading algorithms against deterministic synthetic data
CI/CD Pipelines — Automated testing with consistent market scenarios
Research — Explore funding rate dynamics across venues

Why Deterministic Data?

Random data is useless for engineering. You need:

Reproducibility: If a test fails, you must be able to replay the exact same market conditions to debug it.
Control: Inject specific anomalies (flash crashes, liquidity voids) to test edge cases that might not happen for years in production.
Compliance: Prove your algorithm handles known adverse scenarios before deploying capital.
Speed: Generate 10 years of tick data in minutes, without expensive subscriptions or rate limits.

Quick Start

Installation Methods (Friendly)

Zero install — MCP server is hosted; no local binary to build or run.
Drop-in configs — ready JSONs in configs/ for Claude Desktop, Cursor, VS Code Copilot, and Cline; replace YOUR_API_KEY_HERE with your key.
Public Discovery — endpoints for health and manifest are publicly accessible to allow easy integration with registries like LobeHub.

# Public health check (No API Key required)
curl -s https://mcp.aleatoric.systems/mcp/health

Local Bridge (Inspector & Claude Desktop)

To use this with the official MCP Inspector or Claude Desktop via stdio:

Set your API key:
```
export ALEATORIC_API_KEY="your-key"
```

Run the bridge server:

npx @modelcontextprotocol/inspector python server.py

Examples

See examples/README.md for the curated flow:
- List presets: python examples/list_presets.py --manifest
- Validate config (hash): python examples/validate_config.py --symbol BTC --seed 42
- Funding simulation: python examples/funding_simulation.py --exchange binance
- Validation showcase (hash + optional export): python examples/validation_showcase.py --symbol BTC --seed 42 --duration 60

1. Get an API Key

Create your account at data.aleatoric.systems/get-started. The same registered account and issued API key work across data.aleatoric.systems, sim.aleatoric.systems, and mcp.aleatoric.systems. Public discovery endpoints stay open, but authenticated MCP/data routes require registration first.

2. Configure Your MCP Client

Add to your MCP client configuration:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "aleatoric": {
      "url": "https://mcp.aleatoric.systems/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "aleatoric": {
      "url": "https://mcp.aleatoric.systems/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

VS Code (Copilot)

Edit .vscode/mcp.json:

{
  "servers": {
    "aleatoric": {
      "type": "http",
      "url": "https://mcp.aleatoric.systems/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

Cline

Add via Cline MCP settings:

{
  "aleatoric": {
    "url": "https://mcp.aleatoric.systems/mcp",
    "headers": {
      "X-API-Key": "your-api-key-here"
    }
  }
}

LobeHub (One-Click)

Go to Settings → Agent → Plugin Settings.
Click "Add via JSON" and paste:

{
  "name": "Aleatoric Engine",
  "identifier": "aleatoric-engine-mcp",
  "manifest": "https://mcp.aleatoric.systems/mcp/manifest",
  "type": "remote",
  "url": "https://mcp.aleatoric.systems/mcp",
  "headers": {
    "X-API-Key": "YOUR_API_KEY_HERE"
  }
}

3. Verify Installation

Test the connection (this endpoint is public for discovery):

curl -s https://mcp.aleatoric.systems/mcp/health

Expected output:

{"status": "ok"}

4. Start Using

Ask your AI assistant:

"Generate 1 hour of BTC synthetic order book data with seed 42"

Available Tools

Tool	Description
`get_health`	Lightweight health check returning server status and timestamp
`validate_config`	Validate simulation configuration and get deterministic hash
`generate_dataset`	Generate a batch of synthetic market data
`get_presets`	List available market simulation profiles
`normalize_events`	Normalize raw exchange data to canonical format
`simulate_funding_regime`	Calculate venue-specific funding rates and perp prices
`get_venue_details`	Get exchange adapter capabilities
`get_config_schema`	Get JSON Schema for SimulationManifest
`get_cache_stats`	Statistics about cached datasets
`stream_cache`	Stream cached events via SSE
`export_cache`	Export dataset as Parquet
`examples/validation_showcase.py`	Public demo: health/presets, deterministic hash check, optional cache export

Prompts & Resources

Prompts: Example asks live in README.md (see Example Prompts) and can be reused directly in MCP-capable IDEs.
Resources: The server exposes MCP resources for cache inspection/export; attach outputs via get_cache_stats, stream_cache, or export_cache to feed downstream tools.

Validation Checklist (End-to-End)

Health: curl -s -H "X-API-Key: $ALEATORIC_API_KEY" https://mcp.aleatoric.systems/mcp/health → expect { "status": "ok", "version": "0.5.10", "timestamp": "..." }.
Manifest: python examples/list_presets.py --manifest → prints server name/version and tool list.
Tool Call: python examples/validate_config.py --symbol BTC --seed 42 → expect Valid! Hash: ... with normalized config.
Resource Flow: python examples/funding_simulation.py --exchange hyperliquid → exercises tool + resource outputs; for cache endpoints, call get_cache_stats then stream_cache/export_cache (attach resource in your MCP client). For a quick public validation demo, run python examples/validation_showcase.py --symbol BTC --seed 42 --duration 60 to confirm deterministic hashes and optionally export a cached Parquet.
Offline sanity (no network): python -m compileall examples after installing deps to ensure scripts parse.

Example Prompts

"Validate this config: symbol BTC, seed 42, volatility 0.02"

"List available presets for perpetual futures"

"Simulate 10 days of funding rates on HyperLiquid with spot=50000 and mark=50100"

"What exchanges does Aleatoric support?"

"Export my cached dataset as Parquet"

Direct API Usage

For programmatic access without an MCP client:

import httpx
import os

api_key = os.getenv("ALEATORIC_API_KEY")
base_url = "https://mcp.aleatoric.systems"

with httpx.Client(timeout=30) as client:
    # Get available presets
    response = client.get(
        f"{base_url}/mcp/presets",
        headers={"X-API-Key": api_key}
    )
    presets = response.json()

    # Validate a configuration
    config = {
        "symbol": "BTC",
        "seed": 42,
        "tick_size": 0.01,
        "lot_size": 0.001,
        "initial_mid": 50000.0,
        "volatility": 0.02,
    }
    response = client.post(
        f"{base_url}/mcp/config/validate",
        json={"config": config},
        headers={"X-API-Key": api_key}
    )
    result = response.json()
    print(f"Valid: {result['valid']}, Hash: {result['hash']}")

See examples/ for more complete examples.

MCP JSON-RPC 2.0 Protocol

The recommended way to interact with Aleatoric. Standard MCP protocol at POST /mcp.

Protocol Details

Version: 2024-11-05
Transport: HTTP POST with JSON-RPC 2.0
Authentication: X-API-Key header

Methods

Method	Description
`initialize`	Handshake — returns protocol version, server info, capabilities
`tools/list`	List all tools with full JSON Schema `inputSchema`
`tools/call`	Execute a tool by name with arguments
`ping`	Connection health check

Example: tools/call

curl -X POST https://mcp.aleatoric.systems/mcp \
  -H "X-API-Key: $ALEATORIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "validate_config",
      "arguments": {
        "config": {"symbol": "BTC", "seed": 42}
      }
    }
  }'

Response Format

All tool results follow MCP content format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "{\"valid\": true, \"hash\": \"sha256:...\"}"}],
    "isError": false
  },
  "error": null
}

API Reference

Full API documentation: www.aleatoric.systems

Primary Endpoint (MCP JSON-RPC)

Endpoint	Method	Description
`/mcp`	POST	MCP JSON-RPC 2.0 protocol endpoint

Discovery Endpoints (Public, No Auth)

Endpoint	Method	Description
`/mcp/tools/list`	GET	Tool discovery with schemas
`/.well-known/mcp.json`	GET	MCP Server Card for registries
`/.well-known/mcp-config`	GET	Session configuration schema

Legacy HTTP Endpoints

Endpoint	Method	Description
`/mcp/manifest`	GET	Server capabilities
`/mcp/health`	GET	Health check
`/mcp/presets`	GET	List presets
`/mcp/config/validate`	POST	Validate config
`/mcp/config/schema`	GET	Get JSON Schema for SimulationManifest
`/data/generate`	POST	Generate batch data (Parquet)
`/mcp/normalize`	POST	Normalize events
`/mcp/simulate_funding_regime`	POST	Funding simulation
`/mcp/venues/{exchange}`	GET	Venue details
`/mcp/caches/stats`	GET	Cache statistics
`/mcp/caches/stream/{key}`	GET	Stream cached data (SSE)
`/mcp/caches/export/{key}`	GET	Export as Parquet

Pricing

Plan	Price	Includes
Starter	$249/mo	14-day trial, basic presets
Pro	$1,250/mo	All exchanges, priority support
Enterprise	Custom	SLA, dedicated support, custom presets

Start your free trial: www.aleatoric.systems

Support

License

Apache License 2.0 - see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github		.github
assistant		assistant
configs		configs
examples		examples
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PROMPTS.md		PROMPTS.md
README.md		README.md
ROADMAP.md		ROADMAP.md
aleatoric.png		aleatoric.png
conftest.py		conftest.py
llms.txt		llms.txt
mcp.json		mcp.json
package.json		package.json
server.py		server.py

Folders and files

Latest commit

History

Repository files navigation

Aleatoric MCP Client

Overview

⚡ 90-Second Demo

Public Validation Showcase

Use Cases

Why Deterministic Data?

Quick Start

Installation Methods (Friendly)

Local Bridge (Inspector & Claude Desktop)

Examples

1. Get an API Key

2. Configure Your MCP Client

3. Verify Installation

4. Start Using

Available Tools

Prompts & Resources

Validation Checklist (End-to-End)

Example Prompts

Direct API Usage

MCP JSON-RPC 2.0 Protocol

Protocol Details

Methods

Example: tools/call

Response Format

API Reference

Primary Endpoint (MCP JSON-RPC)

Discovery Endpoints (Public, No Auth)

Legacy HTTP Endpoints

Pricing

Support

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages