MCP SERVER

An MCP connector for agents.

Drive Mock Machines from an AI agent over the Model Context Protocol — 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 Lab → Workbench → Scenario → Experiment facade — what you can do is identical, only the surface differs.

Try a preset live→ REST API

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_scenarios List the available scenarios with their ids, machine counts, and edit flags.

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

list_instances Entity types and counts in a scenario's seeded 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 scenario's seeded experiment tables (CSV/Parquet) and return download links.

Running & managing experiments · authenticated

deploy_scenario Deploy a scenario — from an existing scenario 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}.

get_scenario_yaml Read the YAML of a deployed scenario.

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 Join the waitlist

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