MCP Server

Mimikos includes a built-in MCP server that lets AI agents start mock servers, query endpoints, manage stateful resources, and inspect request logs — all through tool calls.

Your AI coding assistant becomes a first-class client of the mock server. No terminal switching, no curl commands, no copy-pasting IDs between windows.

Setup

Claude Code

claude mcp add mimikos -- mimikos mcp

Restart Claude Code to pick up the new server. To share the config with your team, add -s project which creates a .mcp.json in the project root.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "mimikos": {
      "type": "stdio",
      "command": "mimikos",
      "args": ["mcp"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "mimikos": {
      "type": "stdio",
      "command": "mimikos",
      "args": ["mcp"]
    }
  }
}

Tip

Mimikos must be installed and available on your PATH for the MCP server to work. See Getting Started for installation options.

Available tools

Tool	Description
start_server	Start a mock server from an OpenAPI spec
stop_server	Stop the running mock server
server_status	Check if a server is running and get its details
list_endpoints	List all classified endpoints with behaviors
get_endpoint	Get detailed info about a specific endpoint
manage_state	CRUD operations on stateful resources
request_status	Force a specific status code for the next request to a path
get_request_log	View recent HTTP requests and their status codes

Tool reference

start_server

Start a mock server from an OpenAPI spec file.

Parameter	Type	Required	Default	Description
specPath	string	yes	—	Path to an OpenAPI 3.x spec (YAML or JSON)
port	integer	no	8080	Server port
mode	string	no	deterministic	deterministic or stateful
strict	boolean	no	false	Return 500 if generated responses fail validation
maxDepth	integer	no	10	Max recursion depth for nested schemas
maxResources	integer	no	10000	Max stored resources in stateful mode

start_server(specPath: "./petstore.yaml", mode: "stateful", port: 3000)

Returns the startup summary: spec name, endpoint count, classifications, and any warnings about degraded schemas.

stop_server

Stop the running mock server. No parameters.

stop_server()

server_status

Check whether a server is running and get its configuration.

server_status()

Returns the running state, mode, port, spec path, endpoint count, and resource count (in stateful mode).

list_endpoints

List all endpoints with their behavioral classification.

list_endpoints()

Returns each endpoint’s method, path, behavior (list, fetch, create, update, delete, generic), and confidence level.

get_endpoint

Get detailed information about a specific endpoint.

Parameter	Type	Required	Description
method	string	yes	HTTP method (GET, POST, etc.)
path	string	yes	Route pattern (e.g., /pets/{petId})

get_endpoint(method: "POST", path: "/pets")

Returns the endpoint’s behavior, confidence, success code, request/response schema status, whether examples exist, wrapper keys, and degradation status.

manage_state

Perform CRUD operations on stateful resources. Only works when the server is running in stateful mode.

Parameter	Type	Required	Description
action	string	yes	create, get, list, update, delete, or reset
path	string	yes (except reset)	URL path (e.g., /pets for create/list, /pets/42 for get/update/delete)
body	object	for create/update	JSON request body

manage_state(action: "create", path: "/pets", body: {"name": "Buddy", "tag": "dog"})

Returns the HTTP status code and response body. The reset action clears all stored resources.

request_status

Force a specific HTTP status code for the next request to a given path. Useful for testing error handling.

Parameter	Type	Required	Description
method	string	yes	HTTP method
path	string	yes	Concrete URL path (e.g., /pets/42, not /pets/{petId})
statusCode	integer	yes	The status code to return

request_status(method: "GET", path: "/pets/42", statusCode: 404)

The override applies once — after the next matching request, the endpoint reverts to normal behavior.

Caution

Status overrides apply to HTTP requests made to the mock server (e.g., via curl or your application). They do not affect manage_state tool calls, which bypass the HTTP middleware. Overrides also bypass stateful mode entirely — no state reads or writes occur. The response comes from the deterministic generator using the spec’s schema for that status code.

get_request_log

View the most recent HTTP requests received by the mock server.

Parameter	Type	Required	Description
limit	integer	no	Number of entries to return (default: 20, max: 100)

get_request_log(limit: 5)

Returns each request’s timestamp, method, path, status code, and response time. Useful for verifying that requests reached the server and checking what status codes were returned.

Example workflow

A typical agent session using MCP tools:

Agent: start_server(specPath: "./petstore.yaml", mode: "stateful")
→ Server running on :8080, 5 endpoints classified

Agent: list_endpoints()
→ GET /pets (list), POST /pets (create), GET /pets/{petId} (fetch), ...

Agent: manage_state(action: "create", path: "/pets", body: {"name": "Buddy"})
→ 201, {"id": 7, "name": "Buddy", "tag": "...", ...}

Agent: manage_state(action: "get", path: "/pets/7")
→ 200, {"id": 7, "name": "Buddy", "tag": "...", ...}

Agent: manage_state(action: "list", path: "/pets")
→ 200, [{"id": 7, "name": "Buddy", ...}]

Agent: get_request_log(limit: 3)
→ POST /pets 201, GET /pets/7 200, GET /pets 200

The agent manages the full lifecycle without you leaving your editor or writing curl commands.

AI agent skills

Mimikos ships two AI agent skills that use MCP tools as their primary transport:

mimikos-seed — Seeds a running Mimikos instance in stateful mode with test data. The agent reads your OpenAPI spec, determines resource dependency order, constructs valid request bodies, and creates resources via manage_state tool calls.

mimikos-enhance — Improves your OpenAPI spec by adding property-level examples, error responses, request body markers, and format annotations. Uses context from your source code to generate domain-appropriate values.

See the skill READMEs for setup instructions for Claude Code and Cursor.

Diagnostics

If tool calls aren’t behaving as expected, increase the MCP server’s log verbosity:

Claude Code

claude mcp add mimikos -- mimikos mcp --log-level debug

Cursor

{
  "mcpServers": {
    "mimikos": {
      "type": "stdio",
      "command": "mimikos",
      "args": ["mcp", "--log-level", "debug"]
    }
  }
}

MCP server logs go to stderr, which your editor typically captures in its MCP output panel.