Skip to main content
The Firedrill MCP server lets a coding agent inspect your test definitions, start fake Tools, examine their state, and run a drill without remembering shell commands. It uses the same compiler and SDK as the CLI. No account or model key is needed to start this server. This is not the synthetic Tool MCP endpoint your application connects to. The control server is for the coding agent writing your tests; firedrill serve exposes your fake Tools to the agent being tested.

​
Connect

Install the Firedrill CLI using the quickstart. Add a stdio MCP server in your coding agent’s MCP settings:
Your coding agent controls the surrounding configuration format. The command above does not write its configuration, install dependencies, or edit your application. Initially the server can validate and inspect source and browse the bundled Tool catalog. Ask your coding agent: “Inspect this project’s Firedrill setup and tell me what is missing before we run it.” To allow local execution, add --allow-execution:
Only enable this for a repository you trust. Tool behavior and declared drill targets are local code, not sandboxed code. Targets may launch subprocesses, read their declared environment variables, call model providers, and incur charges. Your coding agent’s tool-approval policy still applies. Do not put secret values in MCP command arguments.

​
Try a fake Tool

Ask your coding agent: “Start this project’s synthetic environment. Find the Tool’s operation contract, call it with test input, and show me what changed. Do not run my application yet.” The server provides these operations: Local execution operations are absent when --allow-execution is not set. A direct attempt to call them is rejected; source-only inspection cannot start a world. Saving a scenario requires confirm: true and the preview’s sourceHash and generation. It captures Tool records and deletions relative to the repository baseline, not an entire running checkpoint. Actors, clock, active faults, pending work, and history are not captured. The preview lists these omissions. The saved scenario can start a new environment; saving it does not change the current environment. environment_connect returns sensitive access details deliberately. Use them in a test-only process or test harness. Never commit them or replace your production configuration. Multiple open environments are isolated from one another. Their connection credentials remain valid through resets, but previously read state/evidence pagination cursors must be restarted after the generation changes.

​
Run your actual agent

Ask: “Run the my-drill drill and show me its result and local report. Do not change the expectation to make a failure pass.” drill_run launches the target declared in the repository and writes reports under .firedrill/. It returns the verdict, build, seeds, run identifiers, and local report locations. A failing assertion is a completed drill with a failed verdict, not a broken MCP connection. You can request up to ten trials of one drill; the default is one. Requests have a two-minute execution deadline by default, adjustable up to ten minutes. Calling environment_call manually only demonstrates a fake Tool’s behavior. It does not prove your application used that Tool. Use drill_run for evidence from a declared target. Targets requiring an in-process runDrills({ agent }) callback remain SDK-driven; the MCP server does not invent a callback or bypass that requirement.

​
Limits and cleanup

  • One server is scoped to one project root. Tool requests cannot choose arbitrary project roots or read arbitrary files.
  • At most four environments may stay open; close one before starting another. Each environment uses the SDK’s normal operation budget.
  • List pages contain up to 100 items. Messages/results are limited to 1 MB; oversized results return an actionable error instead of incomplete JSON.
  • Requests are serialized so a reset cannot overlap another control operation. Disconnecting or interrupting the server cancels a running drill and closes its owned listeners and SQLite handles.
  • Saved reports and world artifacts remain in the project’s ignored .firedrill/ directory. This server does not delete them or upload them.
  • stdout carries MCP messages only. Keep subprocess logs on stderr; never print credentials. This local server does not provide remote authentication or a hosted API.