MCP Tools Reference

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

High-Level Tools

create_expectation

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

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.

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.

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.

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.

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.

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.

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.

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.

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>"
    }
  }
}

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.

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"
      }
    }
  }
}

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.

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.

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.

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.

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.