Assertions¶

mcp-api-test provides built-in assertions for common API validation scenarios. Assertions are optional: when omitted, the tool simply executes the request and reports the response, providing raw data for the agent to reason about independently.

Available assertions¶

Parameter	Type	Description
`required_status_code`	`int`	Assert the response has an exact status code
`required_status_code_range`	`str`	Assert the status code falls within a range
`required_response_fields`	`list[str]`	Assert that specific fields exist in the JSON response
`required_response_contains`	`str`	Assert the response body contains a substring

Status code assertions¶

Exact match¶

Assert the response returns a specific status code:

required_status_code: 201

Range match¶

Assert the status code falls within a range. Two formats are supported:

Wildcard format — matches an entire class of status codes:

required_status_code_range: "2xx"    # matches 200-299
required_status_code_range: "4xx"    # matches 400-499

Explicit range — matches a specific numeric range:

required_status_code_range: "200-299"

Response field assertions¶

Assert that specific fields exist in the JSON response body. Supports nested fields using dot notation:

required_response_fields: ["id", "data.user.name", "data.items"]

For JSON array responses, the assertion checks whether at least one item in the array contains the specified field.

Response content assertions¶

Assert that the response body contains a specific substring. The check is performed against the serialized JSON or raw text:

required_response_contains: "order_id"

Combining assertions¶

Multiple assertions can be combined in a single call. All assertions are evaluated independently, and the overall result passes only if every assertion passes:

required_status_code: 201
required_response_fields: ["id", "created_at"]
required_response_contains: "success"

The response format page shows how assertion results are displayed.