Check whether the mockzilla CLI is available — either on the system PATH, in the bridge's own cache (~/.cache/mockzilla-mcp/), or via a go run invocation. Call FIRST when the user wants to try mockzilla locally. If nothing resolves, the response carries install_options; suggest install_cli to the user and ask them which method (download / go-install / go-run) they prefer.

Install the mockzilla CLI for this user. Three methods — ASK the user which one they want before calling: • download (recommended): fetch the prebuilt binary for this OS/arch from github.com/mockzilla/mockzilla releases (~38MB). Fast, no toolchain needed. • go-install: run go install <module>@v<version> to compile from source. Needs Go on PATH. • go-run: don't install at all — the bridge stores a go run <module>@v<version> invocation. First serve_locally compiles into Go's module cache; later runs are instant. Needs Go. Files land in the bridge's own cache, never on system PATH; blow it away with rm -rf ~/.cache/mockzilla-mcp.

Start ONE mockzilla portable mock server on this machine that serves any number of APIs together — no mockzilla account needed. Pass input as a single spec path / directory / public https URL, OR an array of them to combine multiple APIs into the same server (each becomes a service mounted at //...). Returns {url, port, pid, services} plus example_endpoints, callable URLs for a single spec. Use one of those rather than guessing a path: each service answers under its mount prefix, not at the spec's bare path. Pair with stop_locally(pid) to clean up. Prefer this over deploy_mock_from_* whenever the user says 'try locally', 'experiment', or 'play with' — those tools create persistent hosted bundles, this one is ephemeral. The bridge only runs ONE local server at a time on purpose: if the user wants more APIs, stop the current server and restart with all of them in input.

To test how a client handles a slow or failing API, pass latency and/or errors. These and mount/context work only when input is a single spec or single-service folder.

If the user names a well-known API (stripe, twilio, github, openai, slack, etc.) WITHOUT providing a URL, recall the public OpenAPI spec URL from your training knowledge and pass that. Do NOT pass a catalog ID or slug from list_catalog_products — that catalog is for the HOSTED deploy_mock_from_catalog flow, its ids are not URLs. Examples of public OpenAPI URLs: • Stripe: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json • Twilio: https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/json/twilio_api_v2010.json • GitHub: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json • Petstore: https://petstore3.swagger.io/api/v3/openapi.json

Make an HTTP request to a URL and return {status, headers, body}. Use this to demonstrate a mock by hitting it after serve_locally (e.g. http://localhost:PORT/openapi/pet/findByStatus), to inspect the admin API (/.services returns the registered services, /healthz for liveness), or to verify a freshly-mocked endpoint works. Default scope is localhost only; pass allow_remote: true for arbitrary URLs (rare — the bridge isn't a general-purpose HTTP client).

Quickly mock a single HTTP endpoint without writing an OpenAPI spec. Pass method (default GET), path (the EXACT HTTP path the user described, including all segments), and the response body (object → JSON, string → text). The bridge writes the response into a managed static dir at ~/.cache/mockzilla-mcp/mocks/ and (re)starts a single shared mockzilla server pointing at it.

Pass path AS IS. Do NOT prepend or duplicate any segment. The bridge derives the service name from the first segment for internal grouping, but it does not change the URL the user hits. Examples: • User says GET /pets/{id} → call mock_endpoint with path=/pets/{id} → URL is http://HOST:PORT/pets/{id} • User says POST /orders → path=/orders → URL is http://HOST:PORT/orders • User says GET /v1/users/me → path=/v1/users/me → URL is http://HOST:PORT/v1/users/me

Pass status and/or headers to mock a failure or a redirect with a real body: status: 404 with an error payload, 201 with a Location, 429 with Retry-After. Omit response to send no body at all, which 204 and 304 require. These need mockzilla 2.8.20 or newer; the tool says so if the installed CLI is older. To fail a share of requests instead of every one, use serve_locally with errors.

Path placeholders like {id} are stored as literal directory names — by default ALL placeholder values share the same response. To return different responses for specific values, call mock_endpoint again with a literal value (e.g. /pets/123).

Calling this multiple times accumulates endpoints in the same server — adding POST /pets after GET /pets/{id} keeps both. Mutually exclusive with serve_locally: stop any ad-hoc server first. See mockzilla_docs_search('static directory') for the underlying convention.

List all endpoints currently mocked via mock_endpoint. Returns {endpoints: [{method, service, path, status, headers?, file}], server_url, ui_url}. An endpoint with body: null answers with no body. If a managed server is running, ui_url is the mockzilla UI (opens in a browser, shows endpoints grouped by service plus request inspection). Suggest the UI to the user when they want to explore beyond what the agent can show in chat.

Wipe ALL mocks created via mock_endpoint and stop the managed server. Equivalent to rm -rf ~/.cache/mockzilla-mcp/mocks plus stop_locally. Use when the user wants to start fresh. Does not touch the mockzilla CLI binary or other bridge state.

List the requests the running local server has answered, newest first: method, URL, status, content type, how long it took, and where the response came from (generated, upstream, replay or cache). Use it to show the user what their code actually sent, to confirm a call arrived, or to find the request to look at next. Pass id together with service for one request's full headers and body. Reads the server's own history API, so it needs no account and works entirely on localhost. To ask what is WRONG with the traffic rather than list it, call diagnose_requests.

Explain what is going wrong with the traffic the local server has served, and where each response's data came from. Returns a breakdown by source (generated / upstream / replay / cache), by status and by content type, latency p50/p95/max, and a list of concrete findings: upstream failures that silently fell back to a generated mock, 404s from a wrong mount prefix, a body that is JSON under a non-JSON content type, and unusually slow requests. Prefer this over request_history when the user asks why a response looks wrong, whether data is real or mocked, or why something is slow. Note that a replayed or cached response never reaches the history log, so a call the user made and cannot find here was most likely served from a recording or the cache rather than not happening. Read-only, localhost only.

Configure replay for a service: record a real response once, then serve it back for every matching request (VCR). Writes a replay: block into the service's config.yml.

ASK THE USER TWO THINGS BEFORE CALLING:

1. Record from a real backend, or pin the mock's own output? With upstream_url the recording is the real backend's response. Without it, replay pins the generated response so repeat calls stop returning fresh random data, which is often what 'make it stable' means.

2. One recording for the whole endpoint, or one per input? With no match fields the key is method and path only, so EVERY call to POST /foo replays the first response no matter what it sends. Look at what the endpoint actually takes, then ask which fields distinguish one case from another and pass those as match.

Match fields come from three sources: path (path variables, ignored unless listed), body (dotted paths like data.items[0].name, or "[0].name" for a top-level array, or flat keys for form bodies), and query. Returns recording_scope spelling out what each endpoint is keyed by. Only writes inside the bridge's own mocks dir; for a folder served from the user's project it returns the YAML and the path for them to apply. Config is read at startup, so restart after.

List the replay recordings a service currently holds, so you can tell the user what is pinned and what a matching request will return. Use it after setup_replay to confirm a recording was captured, or when a response looks stale and you suspect it is being replayed rather than produced fresh. Read-only.

Say whether a GitHub repository (or a local folder) would deploy a mock, and what is missing if not. Use it when the user has a repo and asks whether it can serve mocks, or before adding the action to one. Detects which of the two kinds it is: a portable repo of service folders, or a codegen repo that builds a Go server. Returns problems (these stop it deploying), warnings (it deploys but something costs later, such as no teardown trigger, or specs large enough to exhaust a free simulation's 128MB), and workflow_to_add when there is no Mockzilla workflow at all. Read-only: it never changes the repository.

List the user's GitHub repositories so you can ASK which one to publish mocks to. Never pick one yourself. publishes_mocks: true means that repo already has the Mockzilla workflow, so publishing there updates its existing mock instead of creating another. Useful in clients with no shell, where you cannot run gh repo list.

Publish mocks to one of the USER'S OWN GitHub repositories and let the Mockzilla action deploy them at a shareable host of their own, https://.api.mockz.io. The label is the repository name, with -2, -3 if it is taken. No Mockzilla account is needed: the first push registers the repository. This is the free path for a user who is not logged in, and a valid choice for one who is when they want the mocks living in a repo and reviewed like code. If they are logged in and just want a quick hosted mock, prefer deploy_mock_from_* instead, which also gives history and replays in the app.

ASK THE USER FIRST, do not guess:

1. WHICH REPOSITORY. It is theirs, not one you invent. It can be an existing repo, including an app repo they already have, since this only adds a services folder and a workflow. list_github_repos shows the candidates.

2. PRIVATE OR PUBLIC, if it has to be created. visibility is required and has no default. The deployed mock URL is public either way, so say so: whatever is in these responses is readable by anyone with the link.

SIDE EFFECTS: uses the user's own gh login, may create a repository, commits and pushes, and triggers a public deploy. An existing services folder is merged into, not replaced, unless replace is true; an existing workflow is never overwritten.

Mocks here are static: spec-generated or fixed responses. If the user wants real logic or state, this is the wrong tool; that needs the codegen action and a Go server, and this refuses to publish into such a repository. Keep specs small too, since a free simulation has 128MB and a big spec costs far more in memory than on disk: simplify first if needed. Then call wait_for_github_deploy. The host is picked when the deploy runs, so this tool returns no URL and that one does.

Wait for the Mockzilla workflow run to finish and return the live mock URL, as the action printed it in the run's log. Mockzilla picks the host when the deploy runs, so this is the one place to get it. Call after publish_to_github, or after the user pushes. A first deploy takes a minute or two. If it returns with no conclusion it ran out of time: call again.

Take down the mocks a repository serves, freeing its simulation slot. Runs the workflow with delete: true, which needs the workflow_dispatch trigger this bridge writes; a repo whose own workflow lacks it cannot be torn down this way, and the result says so. Pass delete_repo: true to also delete the repository itself, which is permanent and needs the delete_repo scope, so confirm with the user before using it.

Stop the mockzilla server started by serve_locally. Takes no arguments — there's only ever one local server running. Returns {stopped: bool, pid?, reason?}.

List the Mockzilla docs that ship with this bridge: the product docs from mockzilla.org (what a simulation is, deploying, resilient backends, billing, settings, the CLI and this MCP server) and the open-source engine docs under engine/ (configuration, contexts, middleware, replay). Returns each category with its topics' id, title and one-line summary. The docs are files inside the bridge, so this needs no network and no login. Call it before answering a question about Mockzilla, then read the topics that fit.

Return the full markdown of Mockzilla doc topics. Pass topics with one or more ids from mockzilla_docs_topics, or category to read a whole category in one call. A large request returns what fits and lists the rest in remaining: read those in a second call. A link to another topic reads as (topic id). Each topic carries url, its public page, to give the user; don't fetch it, the markdown is the same page.

Search the Mockzilla docs by keyword. Returns the best matching sections {topic, title, heading, snippet} so you know which topics to read. Use it when no topic title from mockzilla_docs_topics clearly fits. Answer from the docs rather than from memory: they describe the product as it is now.

Report the bridge's own version and check whether a newer one is on npm. Returns {bridge_version, bridge_latest, update_available, upgrade_steps}. Call this when the user asks 'is mockzilla-mcp up to date?', or proactively if a tool starts failing in a way that could be a stale-bridge issue.

Log in to Mockzilla cloud so the hosted tools (deploying mocks, listing simulations, the catalog) become available. Opens the Mockzilla login in the user's browser, where they pick an organization and read-only or read-and-write access. Returns right away with the login url. Call it when a hosted tool says it needs a login, then call that tool again once the user approves. Local tools never need it. Side effects: starts a short-lived listener on 127.0.0.1 for the login callback, and saves the login under ~/.config/mockzilla-mcp/.

Log out of Mockzilla cloud on this machine. Revokes the connection and deletes the saved login; hosted tools disappear until the next login. Call it when the user asks to log out or to switch organization or access level.

Scan a directory and report what mockzilla can do with it: top-level OpenAPI spec files (with title and endpoint count) plus any folders of static endpoint files mockzilla can serve. Returns a suggested_input the agent can hand directly to serve_locally. Use this when the user says 'I have a folder of specs/files, what's in it?' or 'mock this directory'. Scans one level only: on a tree of spec folders it names the subdirectories to recurse into. A big folder is summarised up to a cap, with truncated: true and the full spec_file_count.

Summarise an OpenAPI spec or .mockz package without serving it. For a spec, returns {title, version, openapi_version, endpoint_count, paths} with operation IDs. For a package, returns its manifest. Pass input as a local file or a public https URL. Use this when the user wants to know what's in a spec or package before deciding whether to serve or deploy it.

Check an OpenAPI spec for schemas no value can satisfy, such as an array with a scalar enum or additionalProperties: false next to oneOf properties. Mockzilla can't generate valid responses for these, so requests to affected endpoints fail validation. Returns {clean, defect_count, defects: [{rule, path, detail}], truncated}; at most 50 defects are listed. Pass input as a local spec file or a public https URL. Use it before serving or deploying a spec, or when a mock returns unexpected validation errors. OpenAPI 3.x only.

Simplify an OpenAPI spec: drop or reduce union types (anyOf/oneOf), strip x-* extensions, and optionally limit the number of optional properties per schema. Writes the simplified spec to disk and returns its path. Use this when a spec is too large or too complex to mock cleanly (deeply nested unions, hundreds of optional fields) — the output is a faithful subset the agent can hand to serve_locally.

Optional-property handling: • omit optional to keep every optional property • optional: N keeps exactly N per schema (0 drops them all) • optional_min/optional_max (must come together) picks a random count in that range per schema

Pass config for an oapi-codegen-dd codegen.yml when the user wants filter + overlay + prune applied before simplification.

Pack a directory of mockzilla services into a .mockz archive for easier distribution or sharing. The archive carries a manifest (name, description, mounts, modes, git source) so the runtime can register every service without re-walking the tree. Hand the resulting .mockz to anyone — they can serve it with serve_locally, even from a URL. Use this when the user wants to share a working mock setup, snapshot one for a teammate, or publish it.

Defaults: output is <basename>.mockz next to dir. Git metadata (remote, ref, commit) is auto-embedded when dir is inside a git tree — pass skip_git: true to suppress.

Return the org, role and access (read or write) the current MCP credential is scoped to. Use this once at the start of a session to know which org you are acting in. A read connection cannot deploy; the user has to log in again with write access.

List the catalog specs (Stripe, Adyen, etc.) available to attach to a HOSTED sim on mockzilla.org. Returns recommended runtime settings the agent should compare against the org's tier before suggesting a deploy. Pass search to substring-match by slug or name. The returned ids/slugs are ONLY usable with deploy_mock_from_catalog — they are NOT URLs and NOT valid input for serve_locally. If the user wants to try a catalog product locally instead, skip this tool and call serve_locally with the public OpenAPI URL for the service (recall it from your training knowledge — Stripe, Twilio, etc. all publish OpenAPI specs on GitHub).

Create a HOSTED, SHAREABLE mock from a catalog spec (Stripe, Adyen, etc.) on mockzilla.org. The mock persists in the user's account and gets a stable URL anyone with the link can hit. Use this when the user wants something durable, team-visible, or reachable from outside their machine — NOT for ephemeral local exploration (use serve_locally for that). Pass catalog_spec_id from list_catalog_products; mount_path defaults to the spec slug. The returned sim is in deploying state -- follow up with wait_for_deploy to receive the live URL.

Create a HOSTED, SHAREABLE mock on mockzilla.org from an inline OpenAPI 3.0+ spec (YAML or JSON in the spec field, 4MB cap). The mock persists in the user's account and gets a stable URL anyone with the link can hit. Use this when the user pastes spec content AND wants a durable, team-visible result — NOT for ephemeral local exploration (use serve_locally for that). The returned sim is in deploying state — follow up with wait_for_deploy to receive the live URL.

Create a HOSTED, SHAREABLE mock on mockzilla.org from an OpenAPI 3.0+ spec at a public https URL. The server fetches the spec (SSRF-protected) and parses it. Use this when the user gives you a spec URL AND wants a durable, team-visible result — NOT for ephemeral local exploration (use serve_locally for that, it accepts the same URL form). The returned sim is in deploying state -- follow up with wait_for_deploy to receive the live URL.

Block until a sim's deploy reaches a terminal status (active or failed) or until timeout_s seconds elapse (default 25, max 30). Returns {sim_id, status, urls: {live, dashboard}} — urls.live is set once the deploy is ACTIVE. On timeout the response carries the current non-terminal status (typically deploying); the agent can call wait_for_deploy again with the same sim_id.

List the sims (deployed mocks) accessible to the current org. Returns a page of sim entries with their refs, statuses, and live URLs. Pass search to substring-filter by name or sim_pk, or sim to look up exactly one sim_pk.