Guide

Chaos MCP Server

./le chaos run includes an MCP (Model Context Protocol) server that lets AI assistants query chaos test state, detect problems, and control the chaos scheduler.

Starting

./le chaos run --mcp :8001 --web :8000 --peers 4 --routes 1000

The --mcp flag starts an HTTP MCP server on the given address. The --web flag is required because the MCP server reads from the web dashboard's shared state.

Use --ai-help to print the tool definitions as JSON (for configuring AI clients):

./le chaos run --ai-help

Ze MCP Injection

To inject an MCP server into the Ze daemon started by ./le chaos run:

./le chaos run --ze-mcp 9718 ...

This adds environment { mcp { port 9718; } } to the generated Ze config.

Tools

chaos_status

Full snapshot of the chaos test state: peer counts, route counts, convergence statistics (min/avg/max/p50/p90/p99 with histogram), per-family convergence, throughput, property results.

chaos_problems

Filtered list of actionable issues. Returns an empty JSON array when healthy. Problem types: missing-routes, peer-stuck-down, route-plateau, slow-convergence, dropped-events, property-violation.

chaos_peers

Per-peer detail. Omit the peer argument for a summary of all peers. Provide a peer index for full detail including recent chaos history (last 5 actions).

chaos_scenario

Static scenario metadata: seed, peer count.

chaos_control

Control chaos scheduling. Actions: pause, resume, trigger, rate, stop. The description steers AI to check status before changing anything.

chaos_execute

Escape hatch for arbitrary orchestrator commands. Prefer the specific tools when possible.

Watchdog

The Watchdog is a report consumer that prints structured PROBLEM: lines to stderr for real-time anomaly detection. It runs regardless of whether the MCP server is enabled.

Stateful anomalies (tracked over time)

Anomaly	Detection
Peer not reconnecting	✕
Route count plateau	recv < sent AND no change for 10s
Route regression	recv decreased without chaos withdrawal
Convergence stall	✕

Instant anomalies (single event)

Anomaly	Trigger
Error	EventError
Dropped events	EventDroppedEvents
Property violation	Property transitions pass to fail

All problems are rate-limited: the same (anomaly-type, peer-index) pair prints at most once per 10 seconds.

Protocol

The chaos MCP server speaks JSON-RPC 2.0 over the MCP 2026-07-28 Streamable HTTP transport at the /mcp endpoint. This server uses the same implementation as the ze daemon's MCP server: NewStreamable with the chaos ToolProvider.

The transport is stateless, so every request stands alone: no handshake, no session id to thread. Provider mode changes only which tools the server offers. Provider mode does not change how the server validates a request. A chaos request therefore carries the same standard headers and the same params._meta block as any other MCP request.

./le chaos run configures no token and no auth mode, which infers auth-mode none: an authenticator that accepts every caller as an anonymous identity. There is no unauthenticated code path, only an accept-all authenticator.

curl -s http://127.0.0.1:8001/mcp \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: chaos_status' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"chaos_status","arguments":{},
        "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28",
                 "io.modelcontextprotocol/clientCapabilities":{}}}}'