Using the MCP Server

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

The connector is hosted at https://mcp.mockmachines.dev over Streamable HTTP — point your MCP client at that URL. (It is served at the root of the subdomain, so there is no path to append.) The server identifies itself as mock-machines.

Claude (web, desktop) — Settings → Connectors → Add custom connector, and enter https://mcp.mockmachines.dev.
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 get the preset/exploration tools (see tiers below); to run experiments and author configs, the client presents a bearer token in the Authorization: Bearer <token> header. The server publishes OAuth 2.0 protected-resource metadata at /.well-known/oauth-protected-resource (RFC 9728), so a client that supports it can discover the authorization server and sign you in.

Access tiers & workbenches

Which tools you can call depends on whether you are authenticated. Identity is resolved per request, so one connector serves many callers at once.

Tier	Who	Workbench	Tools
Anonymous	no token	the shared workbench — admin-pinned presets	the preset/exploration tools
Authenticated	bearer token (tier ≥ free)	your own per-user workbench	preset tools + experiment and config-authoring tools

Talk to the PaymentProcessor model

The PaymentProcessor preset models a European payment processor — merchants onboard through verification and run recurring payments routed onto SEPA, BACS, and AUTOGIRO settlement schemes. Once the connector is added, an agent can explore its pre-run experiment with the anonymous tools — no token required:

list_presets                              → find "PaymentProcessor" and its experiment id
get_scenario_summary(PaymentProcessor)    → its machine types (Merchant, Payment, …)
list_instances(Merchant)                  → the merchants and their counts
get_instance(Merchant-00000001)           → one merchant's decoded fields and state
get_available_events(Merchant-00000001)   → which events are eligible, with condition verdicts
request_event(Merchant-00000001, …)       → try an event (in-memory; fires only if conditions hold)
download_dataset                          → the exported tables as CSV/Parquet download links

In a chat this is just natural language — “open the PaymentProcessor preset, show me a merchant, and tell me which events it can take” — the agent picks the tools above. To run your own PaymentProcessor experiment (or author a new scenario), sign in so the authenticated tools become available.

The tools

Exploring presets (anonymous)

Tool	Does
`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)

Tool	Does
`deploy_scenario`	Deploy a scenario — from 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)

Tool	Does
`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.

A typical flow

Explore a preset (anonymous):

list_presets → get_scenario_summary → list_instances → get_instance
            → get_available_events → request_event → download_dataset

Author and run your own scenario (authenticated):

get_config_schema → (model drafts a config) → validate_scenario → analyze_config
   → deploy_scenario → run_experiment → get_run_status → download_dataset

The config the model writes is the same YAML described in the Config YAML reference; a finished run can emit the OSI semantic model alongside its DuckDB database.

Inline widgets

For MCP hosts that render UI (ChatGPT Apps, Claude), several tools attach a self-contained HTML widget: list_presets (a preset browser), get_available_events (an instance view with requestable events), and run_experiment / get_run_status (a live run-status panel). Plain-JSON clients ignore the widget metadata and use the tool output directly.