--- 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.