MCP + API

Two ways in. One engine.

Drive Mock Machines from an AI agent over the Model Context Protocol, or from any HTTP client over the REST API. They are sibling adapters over the same Lab → Workbench → Scenario → Experiment facade — so what you can do is identical, only the surface differs.

Try a preset live→ List scenarios (REST)

USING THE MCP SERVER

An MCP connector for agents.

OVERVIEW

The MCP server exposes Mock Machines as a set of Model Context Protocol tools, so an AI agent — Claude, ChatGPT, or any MCP client — can browse scenarios, run experiments, and author new configs without leaving the conversation.

It is a sibling adapter to the REST API over the same facade — every tool ultimately drives a Lab → Workbench → Scenario → Experiment operation, and the server holds no engine logic of its own.

CONNECTING

Streamable HTTP, served at the subdomain root. The server identifies itself as mock-machines.

# Point any MCP client at the connector — served at the subdomain root.
https://mcp.mockmachines.dev

Claude (web, desktop) — Settings → Connectors → Add custom connector, and enter the URL above.
ChatGPT (Apps / Developer mode) — add a connector with the same URL.
Other MCP clients — register a Streamable-HTTP server at that URL.

Auth is optional. Anonymous callers act in the shared workbench of admin-pinned presets and get the preset/exploration tools. Authenticated callers present a bearer token (Authorization: Bearer <token>), get their own per-user workbench, and unlock the experiment and config-authoring tools. The server publishes OAuth 2.0 protected-resource metadata at /.well-known/oauth-protected-resource for clients that can discover and sign in automatically.

THE TOOLS

Three tiers of tools.

Exploring presets · anonymous

list_presets List the available presets with their experiment ids and scenario summaries.

get_scenario_summary A scenario's id, name, and machine types (by preset name or scenario id).

list_instances Entity types and counts in a preset's experiment; optionally every instance of a type.

get_instance One entity's fully decoded field map and current state.

get_available_events The events available on an entity's current state, with condition verdicts.

request_event Request an event on an entity — it fires if its conditions hold, no-op otherwise (in-memory only).

download_dataset Export a preset experiment's tables (CSV/Parquet) and return download links.

Running & managing experiments · authenticated

deploy_scenario Deploy a scenario — from a draft, a preset clone, YAML, or structured config_json; mints a new scenario id.

run_experiment Run a scenario's experiment asynchronously for N turns; returns a run id.

get_run_status Poll a run: status (ready / running / error), turn, and entity counts.

checkpoint_experiment Write a checkpoint at the current turn (the experiment stays live).

resume_experiment Resume from a checkpoint (or the newest); rehydrates a hibernated run.

reset_experiment Discard in-memory drift back to the last checkpoint.

hibernate Checkpoint, then free the in-memory handle; the next use resumes the parked state.

get_limits Your entity limits (soft/hard caps) and per-user experiment cap.

Authoring configs · authenticated

get_config_schema The JSON Schema of the config format — feed it to a structured-output model to emit valid configs.

analyze_config A static-analysis report for a config (parallelism, hazards, cycles, unused slots) without deploying.

validate_scenario Validate a config (YAML or config_json) without deploying; returns {valid, errors}.

save_draft / get_draft / list_drafts / delete_draft Manage private, un-deployed config drafts in your workbench.

get_scenario_yaml Read the YAML of a deployed scenario or a draft.

USING THE REST API

Plain HTTP over the same facade.

OVERVIEW

The REST API is a thin HTTP adapter over the Mock Machines facade. It exposes scenarios and experiments as resources, so any HTTP client can browse a deployed scenario, run an experiment, and read back the results.

It is a sibling of the MCP server — both drive the same Lab → Workbench → Scenario → Experiment facade, and neither holds engine logic of its own.

THE HOSTED API

Live and hosted — no local build or server to run. Every endpoint hangs off this base.

# Base URL — liveness probe at /health
https://api.mockmachines.dev

The API is open for reading the curated preset scenarios anonymously — no token required. Creating, running, and deploying scenarios needs a bearer token, which scopes the work to your own private workbench. The MCP connector is the sibling adapter, and the read-only studio is a browser UI over this same API.

ENDPOINTS

Scenarios and experiments.

Scenarios

GET /scenarios List deployed scenarios (presets included).

GET /scenarios/{id} One scenario's metadata.

POST /scenarios Deploy a scenario from a YAML request body; returns the new id. (auth)

DELETE /scenarios/{id} Delete a scenario and all its experiments. (auth)

Experiments · under /scenarios/{id}/experiments

GET /experiments List a scenario's experiments.

GET /experiments/{eid} Status, turn, and entity counts — poll this after a run.

POST /experiments Create (seed) an experiment at turn 0. (auth)

DELETE /experiments/{eid} Delete an experiment. (auth)

POST /experiments/{eid}/run Advance the experiment N turns, or request an event. (auth)

POST /experiments/{eid}/persist Checkpoint at the current closed-turn boundary. (auth)

POST /experiments/{eid}/load Resume a named checkpoint into a new experiment. (auth)

POST /experiments/{eid}/export Export tables to CSV or Parquet. (auth)

GET /experiments/{eid}/db Download the DuckDB database + OSI model as a zip.

GET /experiments/{eid}/events Paginated event log (?from=&limit=).

GET /experiments/{eid}/dataset Dataset metadata (status, counts, file list).

Browsing a ready experiment · under …/experiments/{eid}

GET /entities Machine types with counts.

GET /entities/{type} All instances of a type, fields decoded.

GET /entities/{type}/{id} One instance's field map.

GET /entities/{type}/{id}/actions The current state and available events, each with condition verdicts.

GET ACCESS

Pick a world. Or build your own.

OPTION A · OPEN NOW Try it live→

Explore a pre-built scenario over REST & MCP — no signup.

OPTION B · WAITLIST Request editing access

Author and edit your own scenarios. Rolling out in batches.