Mockzilla is an open-source API mock server. This server lets you install, manage, and interact with it to mock OpenAPI specs or individual HTTP endpoints, locally or hosted.
Setup & Status
Check CLI availability – Detect if Mockzilla is installed on your PATH, bridge cache, or via go run.
Install the CLI – Download a prebuilt binary, compile with go install, or use go run (no system PATH changes).
Check bridge status – Report the current bridge version and whether a newer version is available.
OpenAPI Exploration
Peek at a spec – Summarize an OpenAPI spec (title, version, endpoint count, paths) from a file or public URL without serving it.
Discover specs in a directory – Scan a folder for OpenAPI spec files and static mock directories.
Local Mocking (no account required)
Serve a mock server locally – Start an ephemeral mock server from one or more OpenAPI spec files, directories, or public URLs.
Stop the local server – Stop the server started by serve_locally.
Mock a single endpoint – Quickly mock one HTTP endpoint (any method/path/status/response body) without an OpenAPI spec; endpoints accumulate in a shared managed server.
List mocked endpoints – List all endpoints created via mock_endpoint, along with the server and UI URLs.
Clear all mocked endpoints – Wipe all mocks and stop the managed server for a fresh start.
Call an endpoint – Make an HTTP request to a URL and return the status, headers, and body to verify mocks.
Documentation
List doc topics – List all available Mockzilla documentation topics.
Read a doc topic – Retrieve the full markdown for a specific topic.
Search the docs – Keyword-search across all docs and return top matching sections with snippets.
Hosted Mocking (requires MOCKZILLA_TOKEN)
List deployed simulations – View your currently deployed hosted mock simulations.
Browse the catalog – See available pre-built API catalog products.
Deploy a hosted mock – Deploy from a catalog bundle, an OpenAPI spec, or a public URL.
Wait for a deploy – Poll until a deployment is ready and return the live URL.
Enables deploying a mock Stripe sandbox via mockzilla's catalog, allowing testing of Stripe integrations without a real account.
MCP server for Mockzilla - an open-source API mock server for OpenAPI specifications. Let Claude Code, Claude Desktop, Cursor, or Gemini CLI install Mockzilla, inspect OpenAPI specs, and spin up realistic local mock APIs in seconds. No account required for local use.
Source: github.com/mockzilla/mockzilla-mcp
Local API development - mock any OpenAPI spec without a real backend or sandbox account
CI/CD integration testing - zero external dependencies in your pipeline
PSP and payment API mocking - Stripe, PayPal, Adyen from your editor without test accounts
Crypto exchange API mocking - Binance, Bybit without registered accounts
Rate limit protection - develop against OpenAI, Twilio without burning quota
Agentic workflows - let Claude or Cursor spin up and manage mock servers automatically
Related MCP server: mcp-cli-catalog
@mockzilla/mcp exposes two planes of tools to your MCP client.
Works entirely on your machine. Nothing leaves the user's box.
From an agent you can:
Check whether the Mockzilla CLI is installed.
Install Mockzilla into a managed cache (no changes to system PATH).
Inspect an OpenAPI spec (title, version, endpoint count, paths).
Serve any OpenAPI spec locally as a portable mock server.
Mock a single HTTP endpoint without a spec.
List, stop, and clear locally managed mocks.
MOCKZILLA_TOKEN)When MOCKZILLA_TOKEN is set, the bridge forwards extra tools to mockzilla.org's MCP endpoint.
Agents can then:
List deployed sims.
Browse catalog products.
Deploy hosted mocks from a spec, URL, or catalog bundle.
Wait for a deploy and return the live URL.
Without a token, only the local plane is exposed. Agents can still help users explore Mockzilla and run local mocks before they sign up.
You can use these directly from Claude Code, Claude Desktop, Cursor, or Gemini CLI once mockzilla is configured as an MCP server.
"Is the mockzilla CLI installed on this machine?"
"Install Mockzilla for me."
"Spin up the Petstore OpenAPI spec locally so I can curl it."
"What endpoints does https://example.com/openapi.yaml expose?"
"Mock POST /checkout to return a 402 response."
"List the mock endpoints you're managing."
"Stop the mock server you started."
MOCKZILLA_TOKEN)"List the sims I have deployed."
"Show me the catalog products."
"Deploy a Stripe sandbox named stripe-test and give me the live URL."
"Create a hosted mock from this OpenAPI URL on mockzilla.org."
One-liner, no config file editing:
claude mcp add -s user mockzilla -- npx -y @mockzilla/mcp@latest-s user installs for your user account (available in every project).
Drop -s user to scope to the current project only.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"mockzilla": {
"command": "npx",
"args": ["-y", "@mockzilla/mcp@latest"]
}
}
}Restart Claude Desktop after editing.
Easiest: Settings -> MCP Servers -> Add new MCP server and fill in:
Name: mockzilla
Command: npx
Args: -y @mockzilla/mcp@latest
Or edit ~/.cursor/mcp.json directly:
{
"mcpServers": {
"mockzilla": {
"command": "npx",
"args": ["-y", "@mockzilla/mcp@latest"]
}
}
}Restart Cursor after editing.
One-liner, no manual JSON editing:
gemini mcp add -s user mockzilla npx -y @mockzilla/mcp@latest-s user writes to ~/.gemini/settings.json (available in every project).
Drop -s user (or use -s project) to scope to the current directory's .gemini/settings.json.
Or edit the settings file directly:
{
"mcpServers": {
"mockzilla": {
"command": "npx",
"args": ["-y", "@mockzilla/mcp@latest"]
}
}
}Restart the Gemini CLI after editing.
@latest?Without @latest, npx caches the first resolved version and won't pick up new publishes. Pinning to @latest makes npx re-check the registry on every spawn, so a Claude / Cursor / Gemini restart is enough to upgrade. Trade-off: ~200 ms extra startup time.
These tools are always available and never leave the user's machine.
check_cli
Resolve Mockzilla on this machine: system PATH -> bridge cache -> go run invocation. Returns install options if nothing matches.
install_cli
Install Mockzilla into ~/.cache/mockzilla-mcp/. Methods: download (prebuilt from GitHub releases, default), go-install, go-run. Never touches system PATH.
bridge_status
Report the bridge's version, check npm for newer publishes, and surface upgrade steps.
peek_openapi
Summarise an OpenAPI spec without serving it: {title, version, openapi_version, endpoint_count, paths}.
mockzilla_docs_topics
List available Mockzilla doc topics.
mockzilla_docs_read
Return the full markdown for one topic.
mockzilla_docs_search
Keyword search across all docs; returns top sections with snippets.
serve_locally
Start a portable mock server on a free port. Accepts a spec file, directory, or public https URL. Returns {url, port, pid, services}.
stop_locally
Stop a server started by serve_locally.
mock_endpoint
Quickly mock a single HTTP endpoint without an OpenAPI spec. Writes a static response into the managed mocks dir and (re)starts the shared server.
list_mock_endpoints
List all endpoints currently mocked, plus the running server's URL and the Mockzilla UI URL.
clear_mock_endpoints
Wipe all mocks and stop the managed server.
When MOCKZILLA_TOKEN is set, @mockzilla/mcp forwards hosted tools to mockzilla.org's MCP endpoint.
At the time of writing, the hosted surface includes:
get_context
list_sims
list_catalog_products
deploy_mock_from_catalog
deploy_mock_from_spec
deploy_mock_from_url
wait_for_deploy
Refer to the hosted server's docs or the MCP registry entry for the live tool list.
Env var | Default | Purpose |
| unset | Bearer token ( |
|
| Override the hosted endpoint (staging, self-hosted). |
| matches bridge version | Pin a specific Mockzilla CLI version for |
|
| Preferred port for the |
| unset | Read docs from this local directory instead of GitHub (useful when editing docs). |
|
| Override the GitHub repo to fetch docs from. |
|
| Override the branch to fetch docs from. |
The bridge keeps everything under ~/.cache/mockzilla-mcp/:
~/.cache/mockzilla-mcp/
├── bin/mockzilla # downloaded or go-installed binary
├── config.json # { method, version, invocation? }
└── mocks/ # mock_endpoint persists static endpoints here
└── static/
└── <service>/<path>/<method>/index.<ext>rm -rf ~/.cache/mockzilla-mcp fully resets the bridge (binary + all mocked endpoints).
To wipe just the mocks: rm -rf ~/.cache/mockzilla-mcp/mocks.
The system PATH is never touched, so reset doesn't affect a separate brew install of Mockzilla.
Recommended way to stay current:
Pin @mockzilla/mcp@latest in your MCP client config so npx re-checks the registry on every spawn.
Restart Claude Desktop / Cursor / Gemini periodically. That's when the new tarball is fetched.
If something seems off, ask the agent: "Run bridge_status and tell me if @mockzilla/mcp is up to date."
If it's stale, run:
npx clear-npx-cache @mockzilla/mcpand restart your MCP client.
The Mockzilla CLI version is pinned by the bridge (via MOCKZILLA_VERSION in lib/install.js). Updating the bridge updates the pin; the next install_cli call brings the CLI itself up to date.
See CLAUDE.md for project conventions and a walkthrough of adding a new tool.
The bridge has two registries to keep in sync: npm (@mockzilla/mcp) and the MCP registry (server.json). Skipping the second one leaves discovery clients pinned to the previous tarball.
Bump version in package.json.
Run:
make publish-allThis will:
Run the smoke test.
npm publish the new tarball.
Mirror the version into server.json.
Run mcp-publisher publish against the MCP registry.
Commit the server.json bump.
If you only want one side:
make publish for npm only.
make publish-mcp for the MCP registry only (server.json is always re-synced from package.json first).
mcp-publisher must be on PATH (brew install mcp-publisher or follow the installation docs).
mockzilla.org - hosted API simulation, per-PR mock URLs, GitHub Actions integration
mockzilla/mockzilla - the core open-source API mock server
Documentation - full usage guide for portable and codegen modes
Copyright © 2026-present
Licensed under the MIT License
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Returns specific fields and is read-only. No annotations, but the description explains output and usage. Could mention external call but not required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient: first states purpose and output, second gives usage guidance. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple status tool: describes action, return fields, and when to use. No output schema but description covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100%. Description adds meaning by specifying return fields and usage, meeting baseline for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reports bridge version and checks for updates on npm. Names the return fields and describes the action with specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call when user asks if updates exist or proactively when tools fail due to stale bridge. Provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| method | No | GET | |
| headers | No | ||
| body | No | ||
| allow_remote | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals the return shape ({status, headers, body}), default localhost-only scope, and the rarity of allow_remote. However, it could mention rate limits or permissions for making external requests, but the explicit security constraint (localhost default) compensates, making it mostly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph of 4 sentences. It front-loads the main action (HTTP request) and follows with specific use cases and constraints. Every sentence adds value without redundancy, making it concise and easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description covers all necessary aspects: return format, typical use cases, security scope, and limitation (not general-purpose). It is sufficient for an agent to understand and correctly invoke the tool, addressing the complexity of making an HTTP request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% property descriptions, so the description must compensate. It provides meaning for url (example localhost URLs), method (implicit via enum), and allow_remote (rare). Headers and body are not elaborated beyond the schema, but the overall context of making an HTTP request gives them implicit meaning. The description adds value but does not fully detail all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core function: making an HTTP request and returning status, headers, body. It distinguishes itself from sibling tools like mock_endpoint or peek_openapi by providing specific use cases (testing mocks, inspecting admin API, verifying endpoints). This satisfies the specific verb+resource requirement and differentiates from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines when to use the tool (demonstrate a mock, inspect admin API, verify mock endpoint) and when not to (the bridge is not a general-purpose HTTP client, allow_remote is rare). This provides clear context and exclusions, guiding the agent to appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses search paths and response content (install_options), though does not detail whether it executes the CLI or just checks files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and structured, though slightly verbose with user guidance that could be secondary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: inputs (none), actions, and follow-up steps. No output schema, but description implies response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline 4 applies. Description adds no parameter info but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks CLI availability across three specific locations, and distinguishes its use case as the first step for local mockzilla attempts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call FIRST' and provides follow-up action: if unavailable, suggest install_cli with method options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden. It describes the destructive nature (wiping all mocks and stopping server), provides an equivalent command (`rm -rf ~/.cache/mockzilla-mcp/mocks` plus `stop_locally`), and explicitly states what it does NOT affect ('Does not touch the mockzilla CLI binary or other bridge state'), offering full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph. It front-loads the primary action, includes a functional equivalent, and adds clarifying statements. Every sentence serves a purpose, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description provides complete context: what the tool does, how it relates to siblings (`mock_endpoint`, `stop_locally`), its effects, and its limitations. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The description adds meaning by explaining the effect, but since no parameters exist, it cannot add parameter-level detail. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Wipe ALL mocks created via `mock_endpoint` and stop the managed server.' It uses a specific verb ('Wipe') and resource ('ALL mocks'), and distinguishes itself from sibling tools like `mock_endpoint` (which creates) and `stop_locally` (only stops server).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when the user wants to start fresh,' providing a clear usage context. It does not explicitly state when not to use, but the context is sufficient to infer that this is for complete cleanup; alternatives like `stop_locally` exist for partial actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a directory and report what mockzilla can do with it: top-level OpenAPI spec files (with title and endpoint count) plus any static/ subdirs that mockzilla can auto-mock. 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'.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description explains the tool's non-destructive scanning behavior and output format. Reveals it returns a suggested_input for serve_locally, which is helpful. Could add depth limit or side effects, but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, efficient word choice. First sentence states action and output, second gives usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple single-parameter tool with clear purpose. Description covers input, scan behavior, and output. Lacks output schema but hints at return value. Complete enough for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'dir' with 0% schema coverage. Description implies it is a directory path but does not describe its format or constraints. Baseline 3 for single required parameter with implicit meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool scans a directory and reports OpenAPI spec files and static subdirs, with specific details like returning a suggested_input for serve_locally. This distinguishes it from siblings like peek_openapi.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides user utterances that trigger this tool ('I have a folder of specs/files, what's in it?' or 'mock this directory'), giving clear context. Lacks explicit when-not-to-use or alternatives, but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | download |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses installation methods, cache location, system PATH impact, and uninstall procedure. It is transparent about where files land and how to clean up, though could mention potential network usage or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loads the purpose and a key instruction. It could be improved with bullet points for the methods, but remains clear and avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema), the description is complete: it explains each method, side effects (cache location, not on PATH), and how to uninstall. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning beyond the schema: it explains each enum value (download: prebuilt binary, go-install: compile from source, go-run: use go run without install), including size, speed, and dependencies. This is essential given 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Install the mockzilla CLI for this user' and details three specific methods, distinguishing the tool from siblings like check_cli and serve_locally.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs the agent to ask the user which method to use and lists prerequisites for each method (e.g., Go needed for go-install/go-run). It does not explicitly exclude scenarios but provides sufficient context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all endpoints currently mocked via mock_endpoint. Returns {endpoints: [{method, service, path, file}], server_url, ui_url}. 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the return format and UI behavior when server is running; despite no annotations, it sufficiently discloses read-only behavior and UI side effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with return format and usage suggestion; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers the tool's purpose, return structure, and contextual usage advice despite lacking an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, baseline 4; no additional parameter info needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists all endpoints mocked via `mock_endpoint`, distinguishing it from sibling tools like `mock_endpoint` (create) and `clear_mock_endpoints` (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to suggest the UI when the user wants to explore beyond chat, implying this tool is for basic listing while the UI offers richer interaction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
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.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | GET | |
| path | Yes | Path beginning with /. First segment is the service name. | |
| response | No | Response body. Object → JSON. String → text. Default {}. | |
| status | No | ||
| content_type | No | Override content type. Inferred from response type if omitted (object → application/json, string → text/plain). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavioral traits: writes to a managed directory, (re)starts a shared mockzilla server, accumulates endpoints, handles path placeholders as literal directory names, and is mutually exclusive with serve_locally. No annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and front-loaded with essential info, but slightly verbose. Every sentence adds value, though could be trimmed slightly. Examples aid clarity but lengthen text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behaviors and side effects thoroughly, but does not explicitly state what the tool returns (e.g., confirmation, URL). With no output schema, a brief mention of return value would improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond the input schema: explains each parameter with examples, default behavior, and nuances (e.g., response type inference, path placeholders). The description compensates for any schema gaps, with 60% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Quickly mock a single HTTP endpoint without writing an OpenAPI spec.' It uses specific verbs and resources, and distinguishes from siblings like serve_locally and clear_mock_endpoints by explaining accumulation and mutual exclusivity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance, including parameter defaults and path handling. Warns against prepending segments, explains placeholders, and contrasts with serve_locally ('Mutually exclusive... stop any ad-hoc server first'). Includes examples for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full markdown for one mockzilla doc topic. Use this when the user asks a deep question about a specific area (middleware, contexts, codegen, config) and you want full context. For broader questions or when you don't know the right topic, use mockzilla_docs_search first.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic name from `mockzilla_docs_topics` (e.g. 'middleware', 'usage/portable'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description accurately describes read-only behavior. Could explicitly state it is a safe operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, first states purpose, second gives usage guidance. No redundancy, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, description is fully sufficient, explaining purpose, usage, and relation to sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema description already explains source and format. Description adds no extra meaning beyond tool context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns full markdown for one doc topic, distinguishes from sibling `mockzilla_docs_search` by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use for deep, specific questions and to use `mockzilla_docs_search` for broader or unknown topics, providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the mockzilla docs by keyword. Returns the top-scoring sections {topic, heading, snippet} so you can identify which topic to read in full. Use this BEFORE answering questions about mockzilla syntax, conventions, or features you're not 100% sure of — the docs are the source of truth, your training is not.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Free-text query, e.g. 'static directory layout'. | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently describes the output format (topic, heading, snippet) and implies read-only behavior via 'search' and 'identify which topic to read'. However, it does not explicitly state it has no side effects or require authentication, which is acceptable for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. First sentence states action and result format. Second sentence provides usage guidance. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description adequately explains what is returned (topic, heading, snippet). It also provides usage context (use before answering). Could mention that limit controls the number of results, but that is partly in the schema. Overall complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: query is described well in the schema ('Free-text query...'), but limit lacks a description. The tool description adds no additional parameter context beyond the schema. The limit parameter is somewhat self-explanatory with min/max/default, but the description could have clarified its role (e.g., 'number of top results to return').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches docs by keyword and returns top-scoring sections with topic, heading, snippet. It distinguishes from siblings like mockzilla_docs_read (which reads full topics) and mockzilla_docs_topics (which lists topics) by focusing on search. The verb 'search' and resource 'mockzilla docs' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this tool BEFORE answering questions about mockzilla syntax, conventions, or features when uncertain, stating 'the docs are the source of truth, your training is not'. This provides clear context for when to use vs. relying on memory, though it does not explicitly mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the available mockzilla doc topics (e.g. 'usage/portable', 'middleware', 'config/service'). Call this once at the start of a session involving non-trivial mockzilla usage to know what knowledge is available; then call mockzilla_docs_search with a query or mockzilla_docs_read for a specific topic.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description is self-sufficient: it describes a read-only listing operation with no side effects. It does not contradict any annotations. The behavior is obvious from the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the purpose with examples, second provides usage guidance. No wasted words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully covers what the tool does, when to use it, and how it relates to siblings. No missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage (empty). The description adds meaning beyond the schema by explaining the purpose, examples, and contextual usage. Baseline for 0 params is 4, and the description meets it well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists available mockzilla doc topics with examples (e.g., 'usage/portable', 'middleware'), and distinguishes it from sibling tools by explaining when to use each (search and read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to call once at the start of a session involving non-trivial mockzilla usage, and then suggests calling `mockzilla_docs_search` or `mockzilla_docs_read` for specific topics. Provides clear when-to-use and next steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarise an OpenAPI spec without serving it. Returns {title, version, openapi_version, endpoint_count, paths}. Pass input as a file path or a public https URL. Use this when the user wants to know what's in a spec before deciding whether to serve or deploy it.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description reveals read-only operation, input types, and that it returns summary not full spec. Could mention side effects, but none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main action and return value, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter tool with no output schema, the description covers all essential information: purpose, input format, and return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description adds critical semantics: input can be file path or public https URL, which fully clarifies the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool summarizes an OpenAPI spec without serving it, lists return fields, and contrasts with serve/deploy siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('before deciding whether to serve or deploy it'), and implies alternatives (serve_locally, call_endpoint).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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} once listening. 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.
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
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Spec file path(s), directory, or public OpenAPI URL(s). Pass an array to combine multiple APIs into one server. | |
| port | No | Port to bind on. Omit or pass 0 to let the OS pick a free port. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behaviors: starts a server, returns {url, port, pid, services}, is ephemeral, runs only one server at a time, and requires pairing with stop_locally. Lacks mention of permissions or resource cleanup, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but somewhat lengthy, containing multiple paragraphs and examples. It is well-structured with a clear first sentence, then details and usage guidance, but could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (local server, multiple APIs, output details) and lack of output schema, the description fully explains the behavior, output format, cleanup, and edge cases like well-known APIs. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant value: explains that input can be a single path/directory/URL or an array, each becoming a service mounted at /<service>/. Provides examples of well-known API URLs and cautions against using catalog IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts a mockzilla portable mock server locally, specifying it can serve multiple APIs from spec paths or URLs. It distinguishes itself from sibling deploy_mock_from_* tools by emphasizing ephemeral local usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to prefer this over deploy_mock_from_* when user says 'try locally', 'experiment', or 'play with'. Provides guidance on stopping current server and restarting with all APIs. Also explains how to handle well-known APIs without a URL by recalling public OpenAPI specs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the mockzilla server started by serve_locally. Takes no arguments — there's only ever one local server running. Returns {stopped: bool, pid?, reason?}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: stops server, takes no arguments, returns {stopped: bool, pid?, reason?}. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, each providing essential information. Action is front-loaded. No extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description explicitly states return format and server uniqueness, making it complete for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. Description adds context that it takes no arguments and only one server exists, which is helpful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool stops the mockzilla server started by serve_locally, specifying the action and resource. Distinguishes from sibling tools by explicitly mentioning the server it stops.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context: use after serve_locally when a local server is running. Notes there is only one server. Does not explicitly state when not to use, but the simplicity of the tool makes it adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0bridge_statuscall_endpointcheck_cliclear_mock_endpointsdiscover_specsinstall_clilist_mock_endpointsmock_endpointmockzilla_docs_readmockzilla_docs_searchmockzilla_docs_topicspeek_openapiserve_locallystop_locallyEach tool has a well-defined, distinct purpose. No two tools appear to do the same thing; even closely related tools like mock_endpoint and serve_locally are clearly differentiated by scope and usage.
All tool names follow a consistent verb_noun pattern (e.g., call_endpoint, install_cli, serve_locally). The naming is predictable and readable, with no mix of conventions.
With 14 tools, the server is well-scoped. Each tool covers a necessary functionality for managing mocking workflows without being overwhelming or sparse.
The tool set covers installation, local serving, quick mocks, spec handling, and documentation access. A minor gap is the lack of a tool to delete a single mock endpoint, but the overall surface is comprehensive.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI-native mock API server with MCP. Create REST/SOAP mocks from Claude, Cursor, or Windsurf.
Build, validate, and manage API simulations in WireMock Cloud from MCP-compatible AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mockzilla/mockzilla-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server