MCP server for AI agents

Mockzilla ships an MCP server, so a coding agent can start mock APIs for you. Ask it to mock a spec and it installs the CLI, starts a server and hands back the URL, without you leaving the editor.

It runs through npx and needs Node 18 or newer. Nothing else to install. The local half works with no Mockzilla account at all.

Add it to your agent

Claude Code:

claude mcp add -s user mockzilla -- npx -y @mockzilla/mcp@latest

Gemini CLI:

gemini mcp add -s user mockzilla npx -y @mockzilla/mcp@latest

Claude Desktop and Cursor take a config file. Claude Desktop's is ~/Library/Application Support/Claude/claude_desktop_config.json, Cursor's is ~/.cursor/mcp.json, and both want the same block:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Restart the app after editing. Cursor can also do it under Settings -> MCP Servers -> Add new MCP server.

Keep @latest in the command. Without it npx reuses the first version it ever resolved, and a restart never picks up a newer one.

What your agent can do without an account

Every one of these runs on your own machine:

• Set up: check_cli looks for the CLI on your machine, install_cli fetches it into the bridge's own cache, and bridge_status reports whether a newer bridge has been published.
• Read specs: peek_openapi summarises one, info prints its full path list, and discover_specs scans a folder and reports what can be mocked from it.
• Reshape specs: simplify cuts a spec down when it is too heavy to mock cleanly, and pack turns a folder of services into a .mockz archive.
• Run mocks: serve_locally starts a server over one or several specs, stop_locally stops it, and call_endpoint fires a request so the agent can show you the response.
• Mock without a spec: mock_endpoint pins a single path to a response you describe, with list_mock_endpoints and clear_mock_endpoints alongside it.
• Read the engine docs: mockzilla_docs_topics, mockzilla_docs_search and mockzilla_docs_read, so answers about configuration come from the documentation instead of the model's memory.

install_cli never edits your PATH. It keeps its own copy, so a brew install stays untouched.

Connect your account

With a key set, the agent also reaches your organization: it can list what you have deployed, browse the catalog, and deploy a hosted simulation that keeps answering after the agent stops.

Create the key first. Open Settings, then the API Keys tab, and click Create key. Give it the Editor role if the agent should deploy, Viewer if it should only read. The key is shown once.

Then pass it as MOCKZILLA_TOKEN. In Claude Code:

claude mcp add -s user mockzilla -e MOCKZILLA_TOKEN=mz_... -- npx -y @mockzilla/mcp@latest

In a config file:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"],
      "env": { "MOCKZILLA_TOKEN": "mz_..." }
    }
  }
}

Seven more tools appear once it is set:

• get_context reports which organization and role the key carries.
• list_sims pages through the simulations you can see, with their URLs and statuses.
• list_catalog_products browses the catalog.
• deploy_mock_from_catalog, deploy_mock_from_spec and deploy_mock_from_url create a hosted simulation from a catalog entry, a pasted spec or a spec URL.
• wait_for_deploy waits for one to go active and returns its live URL.

A deploy through an agent is a deploy like any other: it counts against your plan and shows up in the app.

Settings

Four environment variables, all of them optional:

• MOCKZILLA_TOKEN is your API key. The hosted tools appear only when it is set.
• MOCKZILLA_MCP_URL sends hosted tool calls somewhere other than https://platform.mockzilla.org/mcp/.
• MOCKZILLA_BIN_VERSION pins which CLI version install_cli fetches. It follows the bridge by default.
• MOCKZILLA_MANAGED_PORT is the preferred port for the mock_endpoint server, 2200 by default. A busy port falls back to a free one.

Where its files live

Everything the bridge keeps sits under ~/.cache/mockzilla-mcp/: the CLI it installed, and the endpoints mock_endpoint wrote. Deleting that folder resets it completely, and a brew install of the CLI is not affected.

To wipe only the mocked endpoints, ask the agent to run clear_mock_endpoints.

Where to go next

• CLI reference
• Start from the catalog
• Deploy and URLs

The bridge is open source: mockzilla/mockzilla-mcp.