--- title: MCP Tools Reference description: Full reference for every MCP tool exposed by MockServer, including create_expectation, verify_request, retrieve, debug, OpenAPI, and LLM mocking tools. shortTitle: MCP Tools Reference layout: page pageOrder: 2 section: 'AI Integration' subsection: true sitemap: priority: 0.8 changefreq: 'monthly' lastmod: 2026-05-26T00:00:00+00:00 ---

MockServer's MCP server exposes a comprehensive set of tools that AI assistants can use to interact with MockServer. Tools are divided into high-level tools (simplified parameters for common tasks) and low-level tools (full JSON passthrough for advanced use cases).

Tool Overview

Tool	Description	Level
`create_expectation`	Create a mock expectation	High
`verify_request`	Verify a request was received N times	High
`verify_request_sequence`	Verify requests were received in order	High
`retrieve_recorded_requests`	Get recorded requests	High
`retrieve_request_responses`	Get request-response pairs	High
`clear_expectations`	Clear matching expectations and/or logs	High
`reset`	Reset all MockServer state	High
`get_status`	Server status and ports	High
`create_forward_expectation`	Create a forwarding proxy expectation	High
`debug_request_mismatch`	Diagnose why a request did not match	High
`explain_unmatched_requests`	Explain recent unmatched requests with ranked diagnostics	High
`stop_server`	Stop the MockServer instance	High
`create_expectation_from_openapi`	Generate expectations from an OpenAPI spec	High
`create_expectations_from_recorded_traffic`	Convert recorded proxy traffic into mock expectations	High
`verify_traffic_against_openapi`	Verify recorded traffic conforms to an OpenAPI spec	High
`run_contract_test`	Send example requests from an OpenAPI spec and validate responses	High
`run_resiliency_test`	Send malformed and boundary-case requests to verify error handling	High
`record_llm_fixtures`	Snapshot recorded LLM/MCP traffic into a committable fixture file	High
`load_expectations_from_file`	Load expectations from a fixture file for replay	High
`mock_llm_completion`	Create a single-turn LLM completion expectation for any supported provider	High
`create_llm_conversation`	Create a multi-turn scripted LLM conversation with optional per-session isolation	High
`verify_tool_call`	Assert an agent called a named tool, from recorded LLM requests	High
`explain_agent_run`	Summarise a recorded agent run (turns, tool-call sequence)	High
`verify_structured_output`	Validate recorded LLM responses' JSON output against a JSON Schema	High
`verify_cost_budget`	Assert the total estimated USD cost of recorded LLM responses is within a budget	High
`detect_llm_drift`	Replay a cassette against the live provider and report structural drift	High
`mock_adversarial_llm_response`	Mock a hostile/malformed LLM response to test agent resilience	High
`run_mcp_contract_test`	Check a target MCP server conforms to the protocol over Streamable HTTP	High
`list_mock_tools`	Generate MCP tool definitions from the current active mock expectations	High
`raw_expectation`	Full expectation JSON passthrough	Low
`raw_retrieve`	Full retrieve with correlation ID filtering	Low
`raw_verify`	Full verification JSON	Low

High-Level Tools

create_expectation

Create a mock expectation that matches incoming requests and returns a specified response.

Parameter	Type	Required	Description
`method`	string	Yes	HTTP method to match (GET, POST, PUT, DELETE, etc.)
`path`	string	Yes	URL path to match (e.g. `/api/users`)
`statusCode`	integer	No	HTTP status code to return. Defaults to 200.
`responseBody`	string or object	No	Response body to return. Strings are sent as-is; objects are serialised as JSON.
`responseHeaders`	object	No	Response headers as key-value pairs
`times`	integer	No	Number of times the expectation should be used. Defaults to unlimited.
`timeToLive`	string	No	How long the expectation remains active, in format `<number> <UNIT>` (e.g. `"60 SECONDS"`). Defaults to unlimited.

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_expectation",
    "arguments": {
      "method": "GET",
      "path": "/api/users",
      "statusCode": 200,
      "responseBody": "{\"users\": [{\"id\": 1, \"name\": \"Alice\"}]}",
      "responseHeaders": {
        "content-type": "application/json"
      }
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"created\",\"count\":1}"
      }
    ],
    "isError": false
  }
}

verify_request

Verify that a specific request was received by MockServer a certain number of times.

Parameter	Type	Required	Description
`method`	string	No	HTTP method to match
`path`	string	Yes	URL path to match
`atLeast`	integer	No	Minimum number of times the request must have been received
`atMost`	integer	No	Maximum number of times the request must have been received

Example request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "verify_request",
    "arguments": {
      "method": "POST",
      "path": "/api/orders",
      "atLeast": 1,
      "atMost": 3
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Verification passed"
      }
    ],
    "isError": false
  }
}

verify_request_sequence

Verify that a sequence of requests was received in the specified order.

Parameter	Type	Required	Description
`requests`	array	Yes	Ordered array of request matchers, each with optional `method` and `path` fields

Example request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "verify_request_sequence",
    "arguments": {
      "requests": [
        { "method": "POST", "path": "/api/login" },
        { "method": "GET", "path": "/api/profile" },
        { "method": "POST", "path": "/api/logout" }
      ]
    }
  }
}

retrieve_recorded_requests

Retrieve requests that have been recorded by MockServer.

Parameter	Type	Required	Description
`method`	string	No	Filter by HTTP method
`path`	string	No	Filter by URL path
`limit`	integer	No	Maximum number of requests to return

Example request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "retrieve_recorded_requests",
    "arguments": {
      "path": "/api/payments",
      "limit": 10
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"method\": \"POST\", \"path\": \"/api/payments\", \"headers\": {\"content-type\": [\"application/json\"]}, \"body\": {\"amount\": 99.99}}]"
      }
    ],
    "isError": false
  }
}

retrieve_request_responses

Retrieve request-response pairs recorded by MockServer, useful for understanding the full HTTP conversation.

Parameter	Type	Required	Description
`method`	string	No	Filter by HTTP method
`path`	string	No	Filter by URL path
`limit`	integer	No	Maximum number of pairs to return

Example request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "retrieve_request_responses",
    "arguments": {
      "path": "/api/users",
      "limit": 5
    }
  }
}

clear_expectations

Clear expectations and/or recorded requests and logs that match the specified request matcher.

Parameter	Type	Required	Description
`method`	string	No	HTTP method to match
`path`	string	No	URL path to match
`type`	string	No	What to clear: `ALL`, `LOG`, or `EXPECTATIONS`. Defaults to `ALL`.

Example request:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "clear_expectations",
    "arguments": {
      "path": "/api/users",
      "type": "EXPECTATIONS"
    }
  }
}

reset

Reset MockServer by clearing all expectations, recorded requests, and logs. This tool takes no parameters.

Example request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "reset",
    "arguments": {}
  }
}

get_status

Retrieve the status of MockServer, including which ports it is listening on. This tool takes no parameters.

Example request:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_status",
    "arguments": {}
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"ports\": [1080]}"
      }
    ],
    "isError": false
  }
}

create_forward_expectation

Create a forwarding proxy expectation that forwards matching requests to a destination host.

Parameter	Type	Required	Description
`path`	string	Yes	URL path to match for forwarding
`host`	string	Yes	Destination host to forward to
`port`	integer	No	Destination port. Defaults to 443.
`scheme`	string	No	Protocol scheme: `HTTP` or `HTTPS`. Defaults to `HTTPS`.

Example request:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "create_forward_expectation",
    "arguments": {
      "path": "/api/.*",
      "host": "api.example.com",
      "port": 443,
      "scheme": "HTTPS"
    }
  }
}

debug_request_mismatch

Diagnose why a request did not match any expectation. This tool compares the provided request details against active expectations and returns detailed mismatch information. Results are ranked by closeness (fewest differing fields first), and each mismatched field includes an actionable remediation hint.

Note: This functionality is also available as a REST API endpoint (PUT /mockserver/debugMismatch) and via the Java client (mockServerClient.debugMismatch(request)). See Troubleshooting Matching for details.

Tip: If you want to diagnose mismatches after a test run without reconstructing requests, use explain_unmatched_requests instead, which works from MockServer's traffic log.

Parameter	Type	Required	Description
`method`	string	No	HTTP method of the failing request
`path`	string	Yes	URL path of the failing request
`headers`	object	No	Headers of the failing request
`body`	string	No	Body of the failing request

Example request:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "debug_request_mismatch",
    "arguments": {
      "method": "POST",
      "path": "/api/users",
      "headers": {
        "content-type": "application/xml"
      },
      "body": "<user><name>Alice</name></user>"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"totalExpectations\":2,\"results\":[{\"expectationId\":\"abc-123\",\"expectationPath\":\"/api/users\",\"expectationMethod\":\"POST\",\"matches\":false,\"matchedFieldCount\":15,\"totalFieldCount\":16,\"differingFieldCount\":1,\"differences\":{\"body\":[\"expected JSON body but was XML\"]},\"remediation\":{\"body\":\"check the Content-Type header and body format\"}},{\"expectationId\":\"def-456\",\"expectationPath\":\"/api/orders\",\"expectationMethod\":\"GET\",\"matches\":false,\"matchedFieldCount\":12,\"totalFieldCount\":16,\"differingFieldCount\":4,\"differences\":{\"method\":[\"expected GET but was POST\"],\"path\":[\"expected /api/orders but was /api/users\"]},\"remediation\":{\"method\":\"use method GET not POST\",\"path\":\"use path /api/orders not /api/users\"}}],\"closestMatch\":{\"expectationId\":\"abc-123\",\"expectationPath\":\"/api/users\",\"expectationMethod\":\"POST\",\"remediation\":{\"body\":\"check the Content-Type header and body format\"}}}"
      }
    ],
    "isError": false
  }
}

The results array is sorted by closeness (fewest differing fields first). Each entry includes:

differences — per-field mismatch details explaining what did not match
remediation — actionable hints for each mismatched field, such as "use method POST not GET" or "check the Content-Type header and body format"
matchedFieldCount / totalFieldCount — numeric closeness ranking
closestMatch — the top-ranked result (at the root level) with its remediation hints

explain_unmatched_requests

Returns recent requests that hit MockServer and matched no expectation, with ranked closest-expectation diagnostics and actionable remediation hints. Use this after a failed test run to understand why requests received 404 responses, without needing to reconstruct each failing request.

Note: This functionality is also available as a REST API endpoint (PUT /mockserver/explainUnmatched) and as an MCP resource (mockserver://unmatched).

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of unmatched requests to return. Defaults to 10, maximum 100.

Example request:

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "explain_unmatched_requests",
    "arguments": {
      "limit": 5
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 20,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"unmatchedRequestCount\":1,\"unmatchedRequests\":[{\"timestamp\":\"2026-05-21 12:00:00.000\",\"method\":\"GET\",\"path\":\"/api/users\",\"closestExpectations\":[{\"expectationId\":\"abc123\",\"expectationPath\":\"/api/users\",\"expectationMethod\":\"POST\",\"matches\":false,\"matchedFieldCount\":15,\"totalFieldCount\":16,\"differingFieldCount\":1,\"differences\":{\"method\":[\"expected POST but was GET\"]},\"remediation\":{\"method\":\"use method POST not GET\"}}]}]}"
      }
    ],
    "isError": false
  }
}

Each unmatched request includes a closestExpectations array ranked by closeness (fewest differing fields first). Each expectation entry includes:

differences — per-field mismatch details
remediation — actionable hints such as "use method POST not GET" or "add missing header Authorization"
differingFieldCount / matchedFieldCount — numeric closeness ranking

stop_server

Stop the MockServer instance. This tool takes no parameters. Use with caution as the server will shut down immediately.

Example request:

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "stop_server",
    "arguments": {}
  }
}

create_expectation_from_openapi

Generate mock expectations from an OpenAPI v3 specification. MockServer will create one expectation per operation in the specification, using example responses where available.

Parameter	Type	Required	Description
`specUrlOrPayload`	string	Yes	URL, file path, or inline OpenAPI specification (JSON or YAML)
`operationsAndResponses`	object	No	Map of `operationId` to status code to control which operations and responses are mocked

Example request:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "create_expectation_from_openapi",
    "arguments": {
      "specUrlOrPayload": "https://petstore3.swagger.io/api/v3/openapi.json",
      "operationsAndResponses": {
        "findPetsByStatus": "200",
        "getPetById": "200"
      }
    }
  }
}

create_expectations_from_recorded_traffic

Converts traffic already recorded by MockServer's forwarding/proxy mode into active mock expectations in one step. After observing a real API via a forwarding proxy (e.g. using create_forward_expectation), call this tool to generate expectations that replay the recorded responses. This enables an "observe then mock" workflow: point MockServer at a real API once, record the traffic, then switch to mocked responses.

Parameter	Type	Required	Description
`method`	string	No	Filter recorded traffic by HTTP method (e.g. `GET`, `POST`)
`path`	string	No	Filter recorded traffic by request path (e.g. `/api/users`)
`preview`	boolean	No	When `true`, return the generated expectations as JSON without adding them. Defaults to `false`.

Example request (preview):

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "create_expectations_from_recorded_traffic",
    "arguments": {
      "path": "/api/users",
      "preview": true
    }
  }
}

Example response (preview):

{
  "jsonrpc": "2.0",
  "id": 16,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"preview\",\"count\":1,\"message\":\"Preview of expectations that would be created. Call again with preview=false to activate them.\",\"expectations\":[{\"httpRequest\":{\"method\":\"GET\",\"path\":\"/api/users\"},\"httpResponse\":{\"statusCode\":200,\"body\":\"[{\\\"id\\\":1}]\"}}]}"
      }
    ],
    "isError": false
  }
}

Example request (create):

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "create_expectations_from_recorded_traffic",
    "arguments": {
      "method": "GET"
    }
  }
}

Example response (create):

{
  "jsonrpc": "2.0",
  "id": 17,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"created\",\"count\":2,\"ids\":[\"abc-123\",\"def-456\"]}"
      }
    ],
    "isError": false
  }
}

When no recorded traffic is found, the tool returns a helpful message suggesting you set up a forwarding proxy first.

verify_traffic_against_openapi

Verify the API calls already recorded by MockServer conform to an OpenAPI contract. Pulls recorded request-response pairs from the event log, validates each request and response against the spec, and returns a per-pair conformance report. See Contract Verification for workflow details.

Parameter	Type	Required	Description
`specUrlOrPayload`	string	Yes	OpenAPI spec as a URL, file path, or inline JSON/YAML payload
`method`	string	No	Filter recorded traffic by HTTP method (e.g. `GET`, `POST`)
`path`	string	No	Filter recorded traffic by request path (e.g. `/api/users`)

Example request:

{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "tools/call",
  "params": {
    "name": "verify_traffic_against_openapi",
    "arguments": {
      "specUrlOrPayload": "/specs/api.yaml",
      "method": "GET"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 18,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"conformant\",\"totalPairs\":2,\"passed\":2,\"failed\":0,\"results\":[{\"method\":\"GET\",\"path\":\"/api/users\",\"matchedOperation\":\"GET /api/users\",\"passed\":true},{\"method\":\"GET\",\"path\":\"/api/orders\",\"matchedOperation\":\"GET /api/orders\",\"passed\":true}]}"
      }
    ],
    "isError": false
  }
}

run_contract_test

Send example requests derived from an OpenAPI spec to a running service and check the responses conform. For each operation in the spec, the tool builds a representative request (with path parameters, query parameters, headers, and request body derived from examples and schema defaults), sends it to the specified base URL, and validates the response. See Contract Verification for workflow details.

Parameter	Type	Required	Description
`specUrlOrPayload`	string	Yes	OpenAPI spec as a URL, file path, or inline JSON/YAML payload
`baseUrl`	string	Yes	Base URL of the service under test (e.g. `http://localhost:8080`)
`operationId`	string	No	Optional filter to test only a specific operation by operationId

Example request:

{
  "jsonrpc": "2.0",
  "id": 19,
  "method": "tools/call",
  "params": {
    "name": "run_contract_test",
    "arguments": {
      "specUrlOrPayload": "/specs/api.yaml",
      "baseUrl": "http://localhost:3000"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 19,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"all_passed\",\"totalOperations\":3,\"passed\":3,\"failed\":0,\"results\":[{\"operationId\":\"listUsers\",\"method\":\"GET\",\"path\":\"/api/users\",\"statusCode\":200,\"passed\":true},{\"operationId\":\"createUser\",\"method\":\"POST\",\"path\":\"/api/users\",\"statusCode\":201,\"passed\":true},{\"operationId\":\"getUser\",\"method\":\"GET\",\"path\":\"/api/users/{userId}\",\"statusCode\":200,\"passed\":true}]}"
      }
    ],
    "isError": false
  }
}

run_resiliency_test

Send malformed and boundary-case requests derived from an OpenAPI spec to a running service and report which inputs it failed to handle gracefully. For each operation, the tool generates a bounded mutation catalogue (omitting required fields, type violations, numeric and string boundary violations, oversized strings, and malformed JSON) and classifies each response as HANDLED (4xx) or UNEXPECTED (5xx, 2xx, or connection error). See Resiliency Testing for workflow details.

Parameter	Type	Required	Description
`specUrlOrPayload`	string	Yes	OpenAPI spec as a URL, file path, or inline JSON/YAML payload
`baseUrl`	string	Yes	Base URL of the service under test (e.g. `http://localhost:8080`)
`operationId`	string	No	Optional filter to test only a specific operation by operationId

Example request:

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "run_resiliency_test",
    "arguments": {
      "specUrlOrPayload": "/specs/api.yaml",
      "baseUrl": "http://localhost:3000"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 20,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"failures_detected\",\"totalMutations\":10,\"handled\":7,\"unexpected\":3,\"operationSummaries\":[{\"operationId\":\"createUser\",\"method\":\"POST\",\"path\":\"/api/users\",\"handled\":7,\"unexpected\":3}],\"results\":[{\"operationId\":\"createUser\",\"method\":\"POST\",\"path\":\"/api/users\",\"mutationType\":\"OMIT_REQUIRED_BODY_FIELD\",\"mutationDescription\":\"omit required body field 'name'\",\"statusCode\":400,\"classification\":\"HANDLED\"},{\"operationId\":\"createUser\",\"method\":\"POST\",\"path\":\"/api/users\",\"mutationType\":\"TYPE_VIOLATION\",\"mutationDescription\":\"type violation on field 'age' (expected integer)\",\"statusCode\":500,\"classification\":\"UNEXPECTED\"}]}"
      }
    ],
    "isError": false
  }
}

record_llm_fixtures

Snapshots LLM/MCP traffic recorded through MockServer's forwarding proxy into a committable, secret-free fixture file for deterministic replay. Converts SSE streaming responses (from APIs like Anthropic Claude, OpenAI, etc.) into MockServer's SSE response format for faithful event-by-event replay. Sensitive headers (Authorization, api-key, Cookie, etc.) are automatically redacted. Note that request and response bodies are not redacted — if your application places credentials in a request or response body, review fixture files before committing them to version control.

Parameter	Type	Required	Description
`path`	string	Yes	File path to write the fixture JSON to. The directory must exist.
`host`	string	No	Only include recorded traffic whose request host matches this value
`requestPath`	string	No	Only include recorded traffic whose request path matches this value
`redactBodyFields`	array of string	No	JSON field names whose values are redacted from recorded request/response bodies (in addition to sensitive headers and the `mockserver.fixtureBodyRedactFields` config). Non-JSON bodies are left intact.

Example request:

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "record_llm_fixtures",
    "arguments": {
      "path": "./fixtures/anthropic-chat.json",
      "requestPath": "/v1/messages"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 21,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"written\",\"count\":3,\"file\":\"/absolute/path/to/fixtures/anthropic-chat.json\",\"message\":\"Wrote 3 expectation(s) to /absolute/path/to/fixtures/anthropic-chat.json. Secrets have been redacted. Load with load_expectations_from_file or initializationJsonPath for replay.\"}"
      }
    ],
    "isError": false
  }
}

load_expectations_from_file

Loads expectations from a JSON fixture file and adds them as active mock expectations in MockServer. Use this to replay LLM/MCP traffic previously recorded with record_llm_fixtures. SSE streaming responses in the fixture are replayed with Server-Sent Events.

Parameter	Type	Required	Description
`path`	string	Yes	File path to the fixture JSON file to load. Must contain expectations in MockServer's standard JSON format.
`strict`	boolean	No	Strict VCR mode: register a low-priority catch-all per cassette path so a request matching no recorded fixture returns HTTP `599` instead of falling through. Defaults to the `mockserver.llmVcrStrict` config.
`normalizeRequestBodyFields`	array of string	No	JSON field names to drop from each recorded request body on load; the remaining fields are matched loosely (extra fields in the incoming request are ignored), so volatile per-run values do not block replay.

Example request:

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "load_expectations_from_file",
    "arguments": {
      "path": "./fixtures/anthropic-chat.json"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 22,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"loaded\",\"count\":3,\"file\":\"/absolute/path/to/fixtures/anthropic-chat.json\",\"ids\":[\"abc-123\",\"def-456\",\"ghi-789\"],\"message\":\"Loaded 3 expectation(s) from /absolute/path/to/fixtures/anthropic-chat.json. They are now active and will match incoming requests.\"}"
      }
    ],
    "isError": false
  }
}

mock_llm_completion

Creates a mock LLM completion expectation that returns a provider-correct response from a high-level description of text, tool calls, stop reason, and usage. The response wire format matches the target provider — for example, Anthropic returns the Anthropic Messages API format, OpenAI returns the Chat Completions format. Streaming responses are supported for all providers.

Both provider and path are required. All other parameters are optional.

Parameter	Type	Required	Description
`provider`	string (enum)	Yes	LLM provider: `ANTHROPIC`, `OPENAI`, `OPENAI_RESPONSES`, `GEMINI`, `BEDROCK`, `AZURE_OPENAI`, or `OLLAMA`
`path`	string	Yes	URL path to match (e.g. `/v1/messages`)
`model`	string	No	Model name to include in the response (e.g. `claude-sonnet-4-20250514`)
`text`	string	No	Response text content
`toolCalls`	array	No	Tool/function calls to include. Each entry requires `name` (string) and accepts optional `arguments` (string or object).
`stopReason`	string	No	Stop reason to encode in the provider format (e.g. `end_turn`, `tool_use`, `stop`)
`usage`	object	No	Token usage. Accepts `inputTokens` (integer) and `outputTokens` (integer).
`streaming`	boolean	No	When `true`, the response is delivered as a Server-Sent Events stream. Defaults to `false`.
`outputSchema`	string or object	No	A JSON Schema the response `text` is expected to conform to. Validated as the response is encoded (fail-soft): on a mismatch the body is returned unchanged but an `x-mockserver-structured-output-invalid` header is added and a warning logged. A blank or malformed schema, or absent text, is a no-op. Use this to catch malformed structured-output fixtures; use `verify_structured_output` to assert over recorded traffic.
`chaos`	object	No	Optional fault/chaos profile for resilience testing (see the table below). Also accepted per turn in `create_llm_conversation`.

chaos fields (all optional):

Field	Type	Description
`errorStatus`	integer	HTTP error status to return instead of a normal response (e.g. `429`, `529`). Fires every time unless `errorProbability` is set. A provider error is returned as a normal HTTP response even for a streaming completion.
`retryAfter`	string	Value for the `Retry-After` header on an injected error (e.g. `"30"`).
`errorProbability`	number	Probability 0.0–1.0 of injecting the error. `1.0` (or omitted with `errorStatus` set) always fires; `0.0` never does. Fractional values are non-deterministic unless `seed` is set.
`truncateMode`	string	`NONE` or `MID_STREAM`. `MID_STREAM` truncates a streaming response after a leading fraction of events.
`truncateAtFraction`	number	Fraction 0.0–1.0 of SSE events to keep before truncating (default `0.5`).
`malformedSse`	boolean	Append a malformed (broken-JSON) SSE chunk so the client must handle a corrupt event.
`seed`	integer	Makes a fractional `errorProbability` reproducible.
`quotaName`	string	Enables a stateful request quota (a fixed-window rate limit). Expectations sharing a `quotaName` share one request counter, so you can model an upstream account limit across several mocks.
`quotaLimit`	integer	Maximum requests allowed within the window before further requests are rejected. Requires `quotaName` and `quotaWindowMillis`.
`quotaWindowMillis`	integer	Window length in milliseconds. The window starts on the first request and resets once it elapses.
`quotaErrorStatus`	integer	HTTP status returned when the quota is exceeded (default `429`); the `retryAfter` value, if set, is sent as the `Retry-After` header.

Chaos is deterministic for truncation, malformed SSE, an errorProbability of 0.0 or 1.0, and the stateful quota — safe for repeatable tests. Use a fractional probability (optionally with a seed) only when you intend flakiness. The quota is the deterministic, stateful counterpart to the probabilistic error: it counts real requests and rejects the ones over quotaLimit per window (the count resets on server reset).

Example request (Anthropic text completion):

{
  "jsonrpc": "2.0",
  "id": 30,
  "method": "tools/call",
  "params": {
    "name": "mock_llm_completion",
    "arguments": {
      "provider": "ANTHROPIC",
      "path": "/v1/messages",
      "model": "claude-sonnet-4-20250514",
      "text": "The capital of France is Paris.",
      "stopReason": "end_turn",
      "usage": {
        "inputTokens": 12,
        "outputTokens": 9
      }
    }
  }
}

Example response (success):

{
  "jsonrpc": "2.0",
  "id": 30,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"created\",\"count\":1,\"id\":\"abc-123\",\"provider\":\"ANTHROPIC\"}"
      }
    ],
    "isError": false
  }
}

Example response (unsupported provider):

{
  "jsonrpc": "2.0",
  "id": 30,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":true,\"message\":\"unsupported LLM provider: UNKNOWN_AI\",\"supported\":[\"ANTHROPIC\",\"AZURE_OPENAI\",\"BEDROCK\",\"GEMINI\",\"OLLAMA\",\"OPENAI\",\"OPENAI_RESPONSES\"]}"
      }
    ],
    "isError": false
  }
}

create_llm_conversation

Creates a multi-turn scripted LLM conversation. Each turn is registered as a separate mock expectation wired into a scenario state chain. As the client sends successive LLM requests, MockServer advances through the scripted turns in order, matching on conversation predicates (turn index, latest message content, role, or tool result presence) and returning the configured completion for that turn.

Per-session isolation is optional. When isolateBy is set, each unique value of the specified header, query parameter, or cookie gets its own independent state chain, so concurrent test sessions do not interfere with each other.

provider, path, and turns are required. All other parameters are optional.

Parameter	Type	Required	Description
`provider`	string (enum)	Yes	LLM provider: `ANTHROPIC`, `OPENAI`, `OPENAI_RESPONSES`, `GEMINI`, `BEDROCK`, `AZURE_OPENAI`, or `OLLAMA`
`path`	string	Yes	URL path to match (e.g. `/v1/messages`)
`model`	string	No	Model name to include in each response
`isolateBy`	object	No	Per-session isolation configuration. Requires `source` (`header`, `queryParameter`, or `cookie`) and `name` (the header/parameter/cookie name to read the session key from).
`turns`	array	Yes	Ordered list of conversation turns. Each turn is an object with an optional `match` predicate block and an optional `response` block (see below).
`ids`	array of strings	No	Expectation IDs to assign to each generated turn expectation, one ID per turn in order. When supplied, each expectation is registered with the given ID. Because MockServer's `PUT /mockserver/expectation` performs an upsert when an ID already exists, supplying the same IDs as a previously created conversation replaces that conversation in place. This is how the Composer view's "edit existing" flow updates a conversation without creating duplicates.

Turn match predicates (all optional; all present predicates must be satisfied for the turn to match):

Field	Type	Description
`turnIndex`	integer	Match when the conversation has this many completed assistant turns (0-based)
`latestMessageContains`	string	Match when the latest message in the conversation contains this substring
`latestMessageRole`	string	Match when the latest message has this role: `USER`, `ASSISTANT`, `SYSTEM`, or `TOOL`
`containsToolResultFor`	string	Match when the conversation contains a tool result for the named tool
`semanticMatchAgainst`	string	Opt-in, exploratory: the intent the latest message should express, judged by a runtime LLM. Off by default and ignored unless `mockserver.llmSemanticMatchingEnabled` is set and a backend resolves. Non-deterministic — for exploration only, never for CI assertions.
`normalization`	object	Optional. Clean up the prompt text before `latestMessageContains` / `latestMessageMatches` are checked, so a match is not blocked by cosmetic differences in dynamically-assembled agent prompts. Deterministic — the same prompt always normalises the same way, so it never makes a test flaky. See the table below.

Turn match.normalization fields (all optional):

Field	Type	Description
`collapseWhitespace`	boolean	Collapse runs of spaces, tabs and newlines to a single space and trim. Default `true`.
`lowercase`	boolean	Lowercase the text so capitalisation differences are ignored. Default `false`.
`sortJsonKeys`	boolean	When the prompt is JSON, sort object keys so key ordering does not affect matching. Default `true`.
`dropBuiltInVolatileFields`	boolean	Strip values that change on every run — timestamps, UUIDs, and ids like `req_…` / `msg_…` / `call_…` — before matching. Default `false`.
`dropVolatileFields`	array of string	Names of JSON fields to remove from the prompt before matching (for caller-specific volatile fields).

Turn response fields (all optional):

Field	Type	Description
`text`	string	Response text content
`toolCalls`	array	Tool/function calls. Each entry requires `name` and accepts optional `arguments` (string or object).
`stopReason`	string	Stop reason (e.g. `end_turn`, `tool_use`)
`usage`	object	Token usage: `inputTokens` and `outputTokens`
`streaming`	boolean	Stream this turn's response as SSE. Defaults to `false`.

Each turn may also carry an optional chaos object (a sibling of match and response) with the same fields as the mock_llm_completion chaos profile, to inject faults into that turn's response.

Example request (2-turn conversation isolated by session header):

{
  "jsonrpc": "2.0",
  "id": 31,
  "method": "tools/call",
  "params": {
    "name": "create_llm_conversation",
    "arguments": {
      "provider": "ANTHROPIC",
      "path": "/v1/messages",
      "model": "claude-sonnet-4-20250514",
      "isolateBy": {
        "source": "header",
        "name": "x-session-id"
      },
      "turns": [
        {
          "match": { "turnIndex": 0 },
          "response": {
            "text": "I can help with that. What city are you asking about?",
            "stopReason": "end_turn"
          }
        },
        {
          "match": {
            "turnIndex": 1,
            "latestMessageContains": "paris",
            "normalization": {
              "lowercase": true,
              "dropBuiltInVolatileFields": true
            }
          },
          "response": {
            "text": "Paris is the capital of France.",
            "stopReason": "end_turn"
          }
        }
      ]
    }
  }
}

In the second turn above, normalization lets the turn match whether the prompt says Paris, PARIS or paris, and ignores any per-request timestamps or ids the agent framework injects — so the match stays stable as prompts are reassembled.

Example response:

{
  "jsonrpc": "2.0",
  "id": 31,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"created\",\"count\":2,\"scenarioName\":\"__llm_conv_a1b2c3d4__iso=header:x-session-id\",\"states\":[{\"scenarioState\":\"Started\",\"newScenarioState\":\"turn_1\",\"id\":\"exp-001\"},{\"scenarioState\":\"turn_1\",\"newScenarioState\":\"__done\",\"id\":\"exp-002\"}],\"ids\":[\"exp-001\",\"exp-002\"]}"
      }
    ],
    "isError": false
  }
}

The scenarioName in the response is auto-generated and encodes the isolation key. The states array shows the scenario state progression: Started → turn_1 → __done. Each concurrent session identified by a distinct x-session-id header value advances through its own copy of this state chain.

verify_tool_call

Assert that an agent called a particular tool, by decoding the LLM requests MockServer recorded and inspecting the assistant tool calls in the conversation. Deterministic and read-only — it does not call any LLM. Useful for testing that your agent decided to use the expected tool (and, optionally, with the expected arguments).

Parameter	Type	Required	Description
`provider`	string	Yes	LLM provider whose recorded requests to inspect (e.g. `ANTHROPIC`, `OPENAI`)
`toolName`	string	Yes	Name of the tool the agent should have called
`path`	string	No	Restrict to requests on this path (e.g. `/v1/messages`)
`argumentsRegex`	string	No	Java regex matched against the tool call's argument JSON
`atLeast`	integer	No	Minimum matching calls required (default 1)
`atMost`	integer	No	Maximum matching calls allowed

The result reports count (matching tool calls found) and satisfied (whether the count met the atLeast/atMost constraints); when not satisfied it includes a human-readable message.

{
  "jsonrpc": "2.0",
  "id": 40,
  "method": "tools/call",
  "params": {
    "name": "verify_tool_call",
    "arguments": {
      "provider": "ANTHROPIC",
      "path": "/v1/messages",
      "toolName": "get_weather",
      "argumentsRegex": "Paris",
      "atLeast": 1
    }
  }
}

verify_structured_output

Assert that the structured (JSON) output of recorded LLM responses conforms to a JSON Schema. MockServer decodes each recorded response for the given provider, extracts the assistant's output text, and validates it against the schema. Deterministic and read-only — useful for checking that an agent (or a mocked model) returns schema-valid structured output. Responses that produce no text output are reported separately as skippedNoOutput.

Parameter	Type	Required	Description
`provider`	string	Yes	LLM provider whose recorded responses to validate (e.g. `ANTHROPIC`, `OPENAI`)
`schema`	string	Yes	JSON Schema the output text of each recorded response must conform to
`path`	string	No	Restrict to responses for requests on this path (e.g. `/v1/messages`)

The result reports checked, conforming, nonConforming, skippedNoOutput, and allConform, plus a per-response results array (each with conforms and, on failure, the validation error).

{
  "jsonrpc": "2.0",
  "id": 45,
  "method": "tools/call",
  "params": {
    "name": "verify_structured_output",
    "arguments": {
      "provider": "ANTHROPIC",
      "path": "/v1/messages",
      "schema": "{\"type\":\"object\",\"required\":[\"city\",\"temperature\"]}"
    }
  }
}

explain_agent_run

Summarise an agent run reconstructed from recorded LLM requests — a quick way to see what an agent did without reading raw request bodies. Returns the message count, the number of assistant turns, the ordered sequence of tool-call names (toolCallSequence), the tool-use IDs a result was returned for (toolResultsFor, e.g. "toolu_1"), and the role of the latest message. Deterministic and read-only.

Parameter	Type	Required	Description
`provider`	string	Yes	LLM provider whose recorded requests to summarise
`path`	string	No	Restrict to requests on this path

{
  "jsonrpc": "2.0",
  "id": 41,
  "method": "tools/call",
  "params": {
    "name": "explain_agent_run",
    "arguments": { "provider": "ANTHROPIC", "path": "/v1/messages" }
  }
}

The result also includes a callGraph object: a nodes array (each with id, kind — a message role or TOOL_CALL — and label) and an edges array (each with from, to, and kind: NEXT for message sequence, INVOKES for a turn's tool calls, RESULT linking a tool call to its returned result). The dashboard Sessions view renders this graph per session.

verify_cost_budget

Asserts that the total estimated USD cost of the LLM responses MockServer has recorded is within a budget — a deterministic, read-only cost gate you can run in CI. It decodes each recorded response for the given provider (via the runtime-LLM client SPI), sums the input/output tokens reported in each response's usage, prices them with MockServer's built-in pricing table, and compares the total against maxCostUsd.

Parameter	Type	Required	Description
`provider`	string (enum)	Yes	Provider whose recorded responses to total (`ANTHROPIC`, `OPENAI`, …)
`maxCostUsd`	number	Yes	Cost budget in USD. The assertion passes (`withinBudget: true`) when the total estimated cost is at or below this value.
`model`	string	No	Model id used to price every response (e.g. `claude-sonnet-4`). If omitted, the model is read from each recorded request body; responses whose model has no known price are reported as `unpriceable` and excluded from the total.
`path`	string	No	Only total responses to this request path.

The result reports checked, skippedNoUsage, unpriceable, totalInputTokens, totalOutputTokens, totalCostUsd, maxCostUsd, withinBudget, budgetCheckAuthoritative, and a per-response results breakdown. The pricing table is public list pricing captured 2025-Q4 and kept in sync with the dashboard — treat totals as an estimate, not an invoice.

Important: withinBudget reflects only the responses that could be priced. When unpriceable > 0 (a recorded model has no known price) or checked == 0 (no responses had usage), the total understates the true cost and a passing withinBudget is not trustworthy. Gate your CI step on budgetCheckAuthoritative (true only when at least one response was checked and every checked response was priced) before trusting withinBudget — pin the model param to guarantee everything is priceable.

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "verify_cost_budget",
    "arguments": { "provider": "ANTHROPIC", "model": "claude-sonnet-4", "maxCostUsd": 0.50 }
  }
}

detect_llm_drift

Replay a recorded fixture (cassette) against the live LLM provider and report structural drift in the responses — new fields, removed fields, and changed field types — not semantic/wording differences. This catches the most common VCR problem: a provider changes its response shape and your cassettes silently go stale.

Requires a configured runtime LLM backend (provider environment variables, the mockserver.llmProvider/llmApiKey properties, or a named backend — see Runtime LLM Backend). If none is configured the tool returns {"disabled": true} and does nothing. It fails closed: a network error or non-2xx live response is reported as could-not-check for that exchange, never as drift. Because it calls a real API (keys, tokens, latency, non-determinism), run it in an opt-in or scheduled CI lane — never the per-commit build.

Parameter	Type	Required	Description
`cassettePath`	string	Yes	Path to the recorded fixture JSON whose exchanges are replayed
`provider`	string	Yes	LLM provider the cassette was recorded against
`backendName`	string	No	Named backend from `mockserver.llmBackendsConfig`; otherwise the default backend is resolved from env/properties

The result reports rollup counts (exchanges, drifted, checked, couldNotCheck) and a details array with, per exchange, the addedPaths / removedPaths / typeChangedPaths (or a note when it could not be checked).

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "detect_llm_drift",
    "arguments": { "cassettePath": "fixtures/anthropic-chat.json", "provider": "ANTHROPIC" }
  }
}

mock_adversarial_llm_response

Mock a curated adversarial payload as the LLM response, so you can test that your agent resists hostile or malformed model/tool output. A defensive testing aid — the payloads are short, benign test fixtures (not working exploits), and the response is deterministic.

Parameter	Type	Required	Description
`provider`	string	Yes	LLM provider (the response is rendered in that provider's format)
`path`	string	Yes	Request path to match (e.g. `/v1/messages`)
`payload`	string	Yes	Payload id from the catalog (see below)
`model`	string	No	Model name to report in the response

Catalog of payload ids: prompt_injection_ignore_instructions, prompt_injection_tool_redirect, jailbreak_persona, data_exfiltration_request, malformed_json_payload, empty_response, overlong_repetition. An unknown id returns an error listing the available ids.

{
  "jsonrpc": "2.0",
  "id": 43,
  "method": "tools/call",
  "params": {
    "name": "mock_adversarial_llm_response",
    "arguments": { "provider": "ANTHROPIC", "path": "/v1/messages", "payload": "prompt_injection_ignore_instructions" }
  }
}

run_mcp_contract_test

Check that a target MCP (Model Context Protocol) server correctly implements the protocol over Streamable HTTP — use it to verify an MCP server you built or changed. The tool runs the required JSON-RPC handshake and core methods against the endpoint (initialize, notifications/initialized, ping, tools/list, and unknown-method rejection) and validates the shape of each response (the JSON-RPC 2.0 envelope and required result fields), never the semantics of any tool. It is fully deterministic and involves no LLM. Each request has a 10-second timeout.

Parameter	Type	Required	Description
`targetUrl`	string	Yes	Full URL of the target MCP server's Streamable HTTP endpoint (e.g. `http://localhost:1080/mockserver/mcp`)
`protocolVersion`	string	No	MCP protocol version to advertise during `initialize` (default `2025-03-26`)
`toolName`	string	No	Optional tool to exercise via a `tools/call` shape check; omit to skip (a `tools/call` may have side effects on the target)

Example request:

{
  "jsonrpc": "2.0",
  "id": 44,
  "method": "tools/call",
  "params": {
    "name": "run_mcp_contract_test",
    "arguments": { "targetUrl": "http://localhost:1080/mockserver/mcp" }
  }
}

Example response: the result text is a JSON report with an overall status (all_passed or failures_detected), the negotiated protocolVersion and serverInfo, and a per-check results array (each with check, passed, and any validationErrors):

{
  "jsonrpc": "2.0",
  "id": 44,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"all_passed\",\"protocolVersion\":\"2025-03-26\",\"serverInfo\":{\"name\":\"MockServer\"},\"totalChecks\":5,\"passed\":5,\"failed\":0,\"results\":[{\"check\":\"initialize\",\"passed\":true,\"statusCode\":200,\"detail\":\"session established\"},{\"check\":\"notifications/initialized\",\"passed\":true,\"statusCode\":202},{\"check\":\"ping\",\"passed\":true,\"statusCode\":200},{\"check\":\"tools/list\",\"passed\":true,\"statusCode\":200,\"detail\":\"29 tools advertised\"},{\"check\":\"rejects unknown method\",\"passed\":true,\"statusCode\":200,\"detail\":\"responded with code -32601\"}]}"
      }
    ],
    "isError": false
  }
}

list_mock_tools

Generates Model Context Protocol tool definitions from the current active response expectations, so an AI agent can discover the mocked endpoints as callable tools without prior knowledge of the API. This tool takes no parameters.

Each response expectation with a concrete method and path matcher becomes one tool entry:

name — derived from the HTTP method and path in lower snake_case (e.g. get_api_users), deduplicated and truncated to 64 characters.
description — Mock for METHOD path.
inputSchema — exposes any query parameters declared on the expectation as string properties, plus an optional body property when the expectation matches on a request body.
_mockserver — annotation object with method, path, and expectationId so a caller can route an invocation back to the mock.

Expectations whose method or path is a notted matcher, or that have no response action, are skipped.

Example request (no arguments required):

{
  "jsonrpc": "2.0",
  "id": 50,
  "method": "tools/call",
  "params": {
    "name": "list_mock_tools",
    "arguments": {}
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 50,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"tools\":[{\"name\":\"get_api_users\",\"description\":\"Mock for GET /api/users\",\"inputSchema\":{\"type\":\"object\",\"properties\":{}},\"_mockserver\":{\"method\":\"GET\",\"path\":\"/api/users\",\"expectationId\":\"abc-123\"}},{\"name\":\"post_api_orders\",\"description\":\"Mock for POST /api/orders\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"body\":{\"description\":\"request body\",\"anyOf\":[{\"type\":\"string\"},{\"type\":\"object\"}]}}},\"_mockserver\":{\"method\":\"POST\",\"path\":\"/api/orders\",\"expectationId\":\"def-456\"}}],\"count\":2}"
      }
    ],
    "isError": false
  }
}

The count field gives the total number of tool definitions generated. Use this tool to let an agent inspect what a MockServer instance is currently set up to mock — for example, before deciding whether to call create_expectation or to invoke an already-mocked endpoint.

Low-Level Tools

Low-level tools accept the full MockServer JSON format, giving you complete control over all options. Use these when the high-level tools do not expose a parameter you need.

raw_expectation

Create an expectation using the full MockServer expectation JSON format. This is a passthrough to the PUT /mockserver/expectation REST API.

Parameter	Type	Required	Description
`expectation`	object	Yes	Full expectation JSON as defined in the REST API specification

Example request:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "raw_expectation",
    "arguments": {
      "expectation": {
        "httpRequest": {
          "method": "GET",
          "path": "/api/users",
          "queryStringParameters": {
            "page": ["1"],
            "limit": ["10"]
          }
        },
        "httpResponse": {
          "statusCode": 200,
          "headers": {
            "content-type": ["application/json"]
          },
          "body": "{\"users\": [], \"total\": 0}"
        },
        "times": {
          "remainingTimes": 5,
          "unlimited": false
        }
      }
    }
  }
}

raw_retrieve

Retrieve recorded data using the full MockServer retrieve JSON format. This is a passthrough to the PUT /mockserver/retrieve REST API.

Parameter	Type	Required	Description
`requestDefinition`	object	No	Request matcher JSON to filter results
`type`	string	No	Type of data to retrieve: `REQUESTS`, `REQUEST_RESPONSES`, `RECORDED_EXPECTATIONS`, `ACTIVE_EXPECTATIONS`, or `LOGS`
`format`	string	No	Response format: `JSON`, `JAVA`, or `LOG_ENTRIES`
`correlationId`	string	No	Filter log entries by correlation ID (only applies when type is `LOGS`). Each incoming request is assigned a unique correlation ID that links all log entries for that request's lifecycle.

Example request:

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "raw_retrieve",
    "arguments": {
      "requestDefinition": {
        "path": "/api/.*",
        "method": "POST"
      },
      "type": "REQUEST_RESPONSES",
      "format": "JSON"
    }
  }
}

raw_verify

Verify requests using the full MockServer verification JSON format. This is a passthrough to the PUT /mockserver/verify REST API.

Parameter	Type	Required	Description
`verification`	object	Yes	Full verification JSON as defined in the REST API specification

Example request:

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "raw_verify",
    "arguments": {
      "verification": {
        "httpRequest": {
          "method": "POST",
          "path": "/api/orders",
          "body": {
            "type": "JSON_SCHEMA",
            "jsonSchema": "{\"type\": \"object\", \"required\": [\"orderId\"]}"
          }
        },
        "times": {
          "atLeast": 1,
          "atMost": 5
        }
      }
    }
  }
}

MCP Resources

In addition to tools, MockServer's MCP server exposes resources that AI assistants can read for context. Resources provide real-time visibility into MockServer's current state.

Resource URI	Description
`mockserver://expectations`	All currently active expectations configured on the server
`mockserver://requests`	All recorded requests received by MockServer
`mockserver://logs`	Server logs including request matching, expectation creation, and errors
`mockserver://configuration`	Current MockServer configuration properties
`mockserver://unmatched`	Recent requests that matched no expectation, with ranked closest-expectation diagnostics and remediation hints

Resources are read-only and are updated in real time. AI assistants can use these to understand the current state of MockServer before taking actions. For example, an assistant might read mockserver://expectations to see what mocks are already configured before creating a new one.