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.

Install

git clone <this repo>
cd api-test-mcp
npm install

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

Or 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

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.json and check whether /users/{id} actually returns what it documents.

Agent: (calls load_api_spec, then test_endpoint with a real user id) → "Called it — got a 200, but the response is missing the created_at field your spec marks as required, and role is 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_tests with { auth: { type: "bearer", token: "..." }, includeMutating: true }) → "12 passed, 2 failed, 3 skipped. POST /orders failed schema validation — total_cents came 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_tests and check_health
• Pattern-aware example generation (respect JSON Schema pattern instead 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