Skip to main content
Glama

api-test-mcp

CI npm version npm downloads License: MIT

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

Tool

What it does

load_api_spec

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_endpoints

List every endpoint currently loaded.

call_endpoint

Make a real HTTP call to a documented endpoint. Returns the real status, headers, and body.

validate_response

Check a response body against the JSON schema documented for a given method + path + status.

test_endpoint

call_endpoint + validate_response in one step. The main tool — "does this endpoint actually work as documented?"

run_all_tests

Best-effort contract-test pass across every GET endpoint that needs no required parameters. Pass includeMutating: true to also auto-generate example params/bodies from the schema and attempt POST/PUT/PATCH (off by default — it can write real data). Endpoints still needing manual input are listed as skipped, with the reason.

check_health

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.

diff_api_specs

Compare two versions of a spec (e.g. an old tag vs. main) and flag likely-breaking changes — removed endpoints, newly-required fields, type changes, removed enum values — versus safe additive changes.

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

Available Tools

8 tools
call_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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      19
      442 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI coding agents with accurate OpenAPI contract details to prevent hallucinated API calls, supporting multi-version pinning, endpoint discovery, and request validation.
      42 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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