MockServer's MCP integration provides two powerful tools for verifying that HTTP traffic conforms to an OpenAPI specification. These tools enable both passive verification of already-recorded traffic and active contract testing of a running service.
There are three verification workflows:
verify_traffic_against_openapi) — validate the API calls already recorded by MockServer against an OpenAPI specrun_contract_test) — send example requests derived from an OpenAPI spec to a running service and check the responses conformrun_resiliency_test) — send deliberately malformed and boundary-case requests to a running service and verify it rejects them gracefullyAll tools produce structured per-operation results with pass/fail status and detailed validation errors, making them ideal for AI-assisted development workflows where an agent needs machine-enforceable conformance guardrails.
After capturing traffic through MockServer (e.g. via a forwarding proxy), use verify_traffic_against_openapi to check that every recorded request-response pair conforms to a given OpenAPI specification.
create_forward_expectation)verify_traffic_against_openapi with the OpenAPI specExample prompt:
"Verify that the traffic recorded by MockServer conforms to our API specification at /specs/api.yaml"
The AI assistant will use the verify_traffic_against_openapi tool:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "verify_traffic_against_openapi",
"arguments": {
"specUrlOrPayload": "/specs/api.yaml"
}
}
}Example response (conformant):
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"conformant\",\"totalPairs\":3,\"passed\":3,\"failed\":0,\"results\":[...]}"
}
],
"isError": false
}
}Example response (non-conformant):
{
"status": "non_conformant",
"totalPairs": 3,
"passed": 2,
"failed": 1,
"results": [
{
"method": "GET",
"path": "/api/users",
"matchedOperation": "GET /api/users",
"passed": true
},
{
"method": "POST",
"path": "/api/users",
"matchedOperation": "POST /api/users",
"passed": false,
"responseErrors": [
"response body validation error: ..."
]
}
]
}Use the optional method and path parameters to verify only a subset of the recorded traffic:
{
"name": "verify_traffic_against_openapi",
"arguments": {
"specUrlOrPayload": "/specs/api.yaml",
"method": "POST",
"path": "/api/orders"
}
}Use run_contract_test to actively test a running service by sending example requests derived from an OpenAPI spec and validating the responses.
Example prompt:
"Run contract tests against my service at localhost:3000 using our OpenAPI spec"
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "run_contract_test",
"arguments": {
"specUrlOrPayload": "/specs/api.yaml",
"baseUrl": "http://localhost:3000"
}
}
}Example response:
{
"status": "all_passed",
"totalOperations": 4,
"passed": 4,
"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
}
]
}Use the optional operationId parameter to test only a specific operation:
{
"name": "run_contract_test",
"arguments": {
"specUrlOrPayload": "/specs/api.yaml",
"baseUrl": "http://localhost:3000",
"operationId": "createUser"
}
}Use run_resiliency_test to verify that a running service handles malformed input gracefully. The tool derives a bounded mutation catalogue from each operation in an OpenAPI spec, sends each mutated request to the service, and classifies the outcome.
run_contract_test)Example prompt:
"Run a resiliency test against my service at localhost:3000 using our OpenAPI spec to check that it rejects bad input properly"
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "run_resiliency_test",
"arguments": {
"specUrlOrPayload": "/specs/api.yaml",
"baseUrl": "http://localhost:3000"
}
}
}Example response (all handled):
{
"status": "all_handled",
"totalMutations": 12,
"handled": 12,
"unexpected": 0,
"operationSummaries": [
{
"operationId": "createUser",
"method": "POST",
"path": "/api/users",
"handled": 12,
"unexpected": 0
}
],
"results": [
{
"operationId": "createUser",
"method": "POST",
"path": "/api/users",
"mutationType": "OMIT_REQUIRED_BODY_FIELD",
"mutationDescription": "omit required body field 'name'",
"statusCode": 400,
"classification": "HANDLED"
}
]
}Example response (failures detected):
{
"status": "failures_detected",
"totalMutations": 12,
"handled": 8,
"unexpected": 4,
"operationSummaries": [
{
"operationId": "createUser",
"method": "POST",
"path": "/api/users",
"handled": 8,
"unexpected": 4
}
],
"results": [
{
"operationId": "createUser",
"method": "POST",
"path": "/api/users",
"mutationType": "TYPE_VIOLATION",
"mutationDescription": "type violation on field 'age' (expected integer)",
"statusCode": 500,
"classification": "UNEXPECTED"
}
]
}Use the optional operationId parameter to test only a specific operation:
{
"name": "run_resiliency_test",
"arguments": {
"specUrlOrPayload": "/specs/api.yaml",
"baseUrl": "http://localhost:3000",
"operationId": "createUser"
}
}After implementing a new API endpoint, ask your AI assistant to run a contract test against your local server. The assistant will derive example requests from the spec and verify your implementation returns conforming responses.
After a test run that routes traffic through MockServer, verify that all recorded request-response pairs conform to the spec. This catches both request-side issues (your code sending malformed requests) and response-side issues (the service returning non-conforming responses).
Write your OpenAPI spec first, then use run_contract_test as a guardrail while implementing. The AI assistant can run the contract test after each change, telling you exactly which operations still fail and what the validation errors are.
After implementing an API endpoint, use run_resiliency_test to verify that your service rejects bad input with appropriate 4xx responses rather than crashing with 5xx or silently accepting invalid data. The tool generates boundary-case and malformed inputs automatically from the spec, so you do not need to write negative test cases by hand.
The run_contract_test and run_resiliency_test tools send HTTP requests to the baseUrl provided by the caller. This is intentional — they are designed to test arbitrary services — but it means an MCP client can direct MockServer to make outbound requests to any reachable host.
When MockServer is exposed beyond localhost, secure the MCP control plane to prevent unauthorized use:
controlPlaneJWTAuthenticationRequired configuration property so that only authenticated clients can invoke MCP tools.All outbound requests made by these tools are logged at INFO level, including the target URL, so that unexpected external traffic is visible in the MockServer log.