api-test-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@api-test-mcp Run all contract tests against the staging API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
api-test-mcp
An MCP server that gives Claude Code, Cursor, Windsurf, or any MCP-compatible AI agent the ability to actually call your API and check the response against what your OpenAPI spec promises — not just read the docs and guess.
No API keys, no config, no cost. Works with any OpenAPI/Swagger 3.x spec (URL or local file).
Why this exists
AI agents are great at reading an OpenAPI spec and writing code against it — but they're guessing about whether the real API actually behaves the way the spec says. This gives an agent (or you, in a normal chat) a way to find out for real: call the live endpoint, and check whether the response actually matches the documented schema.
Related MCP server: agent-validator-mcp-server
Install
git clone <this repo>
cd api-test-mcp
npm installAdd it to your MCP client config, e.g. for Claude Code:
claude mcp add api-test -- node /absolute/path/to/api-test-mcp/src/index.jsOr in claude_desktop_config.json / Cursor's MCP settings:
{
"mcpServers": {
"api-test": {
"command": "node",
"args": ["/absolute/path/to/api-test-mcp/src/index.js"]
}
}
}Tools
Tool | What it does |
| Load and dereference an OpenAPI/Swagger spec from a URL or local path. Returns the API title, servers, and every documented endpoint. Call this first. |
| List every endpoint currently loaded. |
| Make a real HTTP call to a documented endpoint. Returns the real status, headers, and body. |
| Check a response body against the JSON schema documented for a given method + path + status. |
|
|
| Best-effort contract-test pass across every GET endpoint that needs no required parameters. Pass |
| One-shot ping across a set of endpoints (or every parameter-free GET in the loaded spec): reports reachability and latency. Handy before a demo or as a CI step. |
| Compare two versions of a spec (e.g. an old tag vs. |
All of the above accept an optional auth preset (bearer, apiKey in a header or query param, or basic) so authenticated APIs aren't limited to hand-building raw headers, and an optional timeoutMs.
Example (what an agent conversation looks like)
You: Load my API spec at
https://api.example.com/openapi.jsonand check whether/users/{id}actually returns what it documents.Agent: (calls
load_api_spec, thentest_endpointwith a real user id) → "Called it — got a 200, but the response is missing thecreated_atfield your spec marks as required, androleis documented as an enum of 3 values but the API returned"superadmin", which isn't one of them."
For an authenticated API:
You: Run a full contract-test pass against my staging API using this bearer token, and include the write endpoints.
Agent: (calls
run_all_testswith{ auth: { type: "bearer", token: "..." }, includeMutating: true }) → "12 passed, 2 failed, 3 skipped.POST /ordersfailed schema validation —total_centscame back as a string, not the integer your spec documents."
Tested against real live traffic
npm test runs three real, unmocked checks, no canned fixtures pretending to be a server:
test/smoke-test.js— loads a spec, makes real HTTPS calls to a live public API, validates the real response, and deliberately feeds in a broken response to confirm validation actually catches mismatches (not just a happy-path check).test/new-features-test.js— auth presets applied to a real outgoing request URL, a real network timeout/abort, a real health-check call, and deterministic offline tests for the spec-diff logic.test/mcp-protocol-test.js— spawns the actual MCP server as a subprocess and talks to it over the real MCP protocol, the same way Claude Code or Cursor would.
CI runs the full suite on every push/PR against Node 18, 20, and 22.
Roadmap
v1.0 shipped contract testing, auth presets, auto-generated example data for mutating endpoints, spec diffing, and health checks. Ideas for what's next:
YAML output mode / a small CLI wrapper for non-MCP use
Configurable retry/backoff for flaky endpoints in
run_all_testsandcheck_healthPattern-aware example generation (respect JSON Schema
patterninstead of a placeholder string)Persisted health-check history (currently one-shot only)
Contributions welcome — see CONTRIBUTING.md. See an endpoint type or spec quirk this doesn't handle well? Open an issue.
License
MIT
Available Tools
8 toolscall_endpointCall a real API endpointA
Make an actual HTTP call to a documented endpoint and return the real status, headers, and body. Does not validate the response — use test_endpoint if you also want schema validation.
Inputs: path (required), method (required), auth, body, +5 more.
check_healthPing a set of endpoints and report reachability/latencyA
One-shot health check: calls each given endpoint (or, if none given, every parameter-free GET in the loaded spec) and reports whether it responded, its status code, and latency. Useful for a quick 'is the API up' pass, e.g. before a demo or as part of CI.
Inputs: auth, baseUrl, endpoints, timeoutMs.
diff_api_specsDiff two versions of an OpenAPI spec for breaking changesA
Compare two OpenAPI/Swagger specs (each a URL or local file path — e.g. an old tag vs. the current main) and report added/removed endpoints plus request/response schema changes, flagging which ones are likely to break existing clients (removed fields, newly-required fields, type changes, removed enum values) versus safe additive changes. Does not affect the spec currently loaded for the other tools.
Inputs: sourceA (required), sourceB (required).
list_endpointsList loaded endpointsA
List every endpoint (method + path) from the currently loaded API spec.
Inputs: no named parameters.
load_api_specLoad an OpenAPI/Swagger specA
Load and fully dereference an OpenAPI/Swagger spec from a URL or local file path (JSON or YAML). Call this first. Returns the API title, servers, and every documented endpoint.
Inputs: source (required).
run_all_testsRun a contract-test pass across the whole APIA
Best-effort run across every GET endpoint that needs no required parameters: calls each one for real and validates the response against the documented schema. Endpoints needing parameters are listed as skipped (use test_endpoint for those individually), and DELETE/OPTIONS/HEAD are never auto-run. Set includeMutating: true to also auto-generate example params/bodies from the schema and attempt POST/PUT/PATCH endpoints — off by default because that can create or modify real data on the live API.
Inputs: auth, baseUrl, timeoutMs, includeMutating.
test_endpointCall and validate an endpoint in one stepA
Call a documented endpoint with real parameters, then validate the real response against its documented schema. Returns pass/fail plus the specific mismatches found. This is the main tool for 'does this endpoint actually work as documented'.
Inputs: path (required), method (required), auth, body, +5 more.
validate_responseValidate a response against the specC
Check a response body against the JSON schema documented for a given method + path + status code.
Inputs: path (required), method (required), status (required), responseBody (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Tools generally target distinct phases (load, list, call, validate, batch-test, health-check, diff), but call_endpoint/test_endpoint and run_all_tests/check_health both invoke live endpoints and could be confused if the goal is simply 'hit the API'. Descriptions do enough to resolve most ambiguity, so not a 5.
All tools use lowercase snake_case imperative verbs (load_, list_, call_, validate_, test_, run_, check_, diff_), and each name clearly signals the action. The pattern is highly consistent and predictable.
8 tools is well-scoped for an API testing server: loading, exploring, calling, validating, running tests, health-checking, and diffing specs. No redundant or extraneous tools are present.
The set covers the full workflow from loading an API spec to listing endpoints, making raw calls, validating responses, batch-running endpoint tests, health-checking, and comparing spec versions. Additional tools like auth management or report generation would be optional rather than obvious gaps.
Maintenance
Related MCP Connectors
AI-callable tools for API mocking, testing, monitoring, security, and automation.
End-to-end API testing — generate and run tests from OpenAPI, curl, Postman, or real user traffic.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Schema-aware API monitoring: diff OpenAPI specs for breaking changes, manage endpoints.
Related MCP Servers
AlicenseAqualityBmaintenanceA deterministic eval engine for coding agents. Your agent claims it fixed the bug—this checks it. The same scenario runs twice against a sandbox of the services your code calls, with failures injected on purpose. It must fail on the old code and pass on the new. The verdict is an exit code, not a model's opinion. Every run leaves a receipt.19442 npm1MIT- AlicenseAqualityDmaintenanceEnables testing and validation of APIs for AI agent compatibility, providing scores, grades, and actionable recommendations.343 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceProvides AI coding agents with accurate OpenAPI contract details to prevent hallucinated API calls, supporting multi-version pinning, endpoint discovery, and request validation.42 npmApache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to inspect, test, validate, compare, and debug HTTP APIs through a structured toolkit, with features such as secret redaction, response contract validation, regression comparison, health checks, and incident investigation workflows.MIT