api-mcp

📦 Published on npm: @hassanjamal/api-mcp — install with npm i -g @hassanjamal/api-mcp (no cloning or building needed).

An MCP (Model Context Protocol) server you plug into any codebase — React Native, web, Flutter, or a backend — that:

1. Discovers every API endpoint in the code (client calls and server routes)

2. Reads or generates an OpenAPI / Swagger spec (if none exists, it builds one)

3. Generates test cases + edge cases for each endpoint, based on its HTTP method and params

4. Auto-logs in per role (from just credentials — finds the login endpoint, extracts the token)

5. Harvests real IDs from responses + JWTs and injects the right resource id into each path param

6. Executes them against your running server — like Postman — scoped to each role's real permissions

7. Reports everything as PDF + XLSX (per-role + an overall audit + the endpoint inventory)

The QA one-call (qa_audit) does all of it from a project path + role logins. All artifacts are written to a .api-mcp/ folder inside the project you point it at.

What it detects

Detection is text/pattern based, so it works on any language without running the code, and handles both :param / {param} / <param> styles and JS ${...} / Dart $var interpolation. Every framework above is covered by the regression suite (npm test) so accuracy can't silently regress.

Related MCP server: REST API MCP Server

Install

Install once, globally — this gives a fast, reliable api-mcp command:

npm i -g @hassanjamal/api-mcp

Requires Node.js 18+. Global install is recommended over npx because npx re-checks the registry on every launch (~6s) and can trip a host's connection health-check; the global binary starts in ~1s.

Connect it to a host

An MCP server does nothing on its own — a host (the app you chat with an AI in) connects to it and exposes its tools. Pick your host:

Claude Code

Register it once for all your projects (user scope):

claude mcp add -s user api-mcp -- api-mcp

Verify: claude mcp list → api-mcp - ✔ Connected. (Mind the spacing: -- api-mcp.)

Cursor

Settings → MCP → Add new server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "api-mcp": { "command": "api-mcp" }
  }
}

Claude Desktop

Edit claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "api-mcp": { "command": "api-mcp" }
  }
}

Restart the host after editing config. The tools (and the /qa-audit, /scan slash commands) then appear to the AI.

Updating: npm i -g @hassanjamal/api-mcp@latest

Slash commands (Claude Code)

Two guided entry points show up as slash commands:

You can also just ask in natural language (see below) — the slash commands are a convenience.

Tools exposed

Once connected, just ask the AI in natural language, e.g.:

"Run a full API audit on this project against http://localhost:3000 using my API_TOKEN."

The AI will call full_audit with the right arguments.

QA workflow (the easy path)

A QA engineer provides only credentials per role — the tool figures out the rest (base URL, login endpoint, token extraction, per-role runs):

"Run a qa_audit on this project with admin a@x.com / pw, teacher t@x.com / pw, student s@x.com / pw."

qa_audit then:

1. Detects the API base URL from the code (.env, axios/Dart baseURL) — or you pass baseUrl

2. Logs in as each role, extracting the token from the response or the JWT (token, accessToken, data.token, jwt…)

3. Harvests real resource IDs from every response + each JWT and injects the correct id into each path param ({courseId} ← a real course id; a bare {id} ← that endpoint's own resource), preferring ids the current role can access — turning wrong-id 404s into real 200s

4. Scopes each role to endpoints its route-guard permits (reads authorizeAdmin(), @Roles('teacher')…), so you get more 200s and far less 403/404 noise

5. Skips session-breaking endpoints (logout/refresh/delete-account/password/register) so a test can't revoke its own token, and paces around rate limits (marks throttled requests not tested, not failed)

6. Writes PDF + XLSX only — overall qa-audit.pdf, per-role qa-report-{role}.pdf/.xlsx, and endpoints.pdf/.xlsx

Read-only by default. Useful arguments:

Web vs mobile — what to provide

The tool always tests the HTTP API, so the inputs are the same for both. The only difference is which source files get scanned for endpoints.

Understanding the results (why not all 200s?)

A healthy API returns a mix of status codes under automated testing — that's it correctly guarding itself, not a sign it's broken. Each request passes gates in order; the status tells you which gate stopped it:

You can't (and shouldn't) get all-200s from automated testing — that would mean the API accepts anything. Only the 500s indicate actual defects.

*The base URL is auto-detected when possible; a mobile app has no "app URL" of its own — you give the backend API URL it talks to (which lives in the app's config).

Configuration

Live execution needs to know your server URL and auth. Provide it either per tool call (baseUrl, bearerToken, headers arguments) or via a config file in the target project root.

Copy api-mcp.config.example.json to api-mcp.config.json:

{
  "baseUrl": "http://localhost:3000",
  "bearerToken": "${API_TOKEN}",
  "headers": { "X-Api-Key": "${API_KEY}" },
  "timeoutMs": 15000,
  "sampleValues": { "id": 1, "body": { "name": "example" } }
}

${ENV_VAR} references are expanded from the environment, so secrets stay out of the file. Secret-looking headers are redacted in saved reports.

Output artifacts (.api-mcp/)

The other tools (scan_endpoints, generate_openapi, run_tests, full_audit) also write:

The HTML & XLSX outputs

• .html reports are self-contained (no internet needed), color-coded by result and status code, and adapt to light/dark themes. Just double-click to open in any browser.

• test-report.xlsx is a styled workbook with three sheets:

  • Summary — totals, pass/fail counts, and a status-code distribution

  • Endpoints — every endpoint with method color badges

  • Test Results — one row per test with complete data (request/response bodies, headers, status, duration, errors), color-coded green/red/amber, with auto-filters enabled.

  Open it in Excel, Google Sheets, or LibreOffice. Secret-looking header values are redacted.

Already have results.json from a previous run and just want the pretty output? Ask the AI to run export_report — it rebuilds the HTML + XLSX from the saved JSON without re-running anything.

Test categories generated

• happy-path — valid request with sample params/body; expects success

• edge-case — non-existent resources, malformed params, empty bodies

• negative — malformed JSON, wrong HTTP method (expects 4xx/405)

• security — same request with credentials stripped (expects 401/403)

Develop from source (contributors)

git clone https://github.com/Hassan-Jamal/Automated_API_MCP.git
cd Automated_API_MCP
npm install
npm run build     # compile to dist/
npm test          # 63 tests: detectors, scanner, auth, schema, harvesting, PDF, etc.

The examples/sample-app/ folder has JS, Dart, and Express files demonstrating the detectors.

Do I need to run my app first?

Depends on the step:

For a React Native or web app, what must be running is the backend API server the app talks to (e.g. http://localhost:3000) — not the emulator or the web frontend. This tool calls the API directly, the same API your app calls. Point baseUrl at that server.

If your project is the backend (Express/NestJS/FastAPI/Flask), start it, then run the tests.

Tip: use dryRun: true on run_tests to preview the requests without sending any — handy before pointing it at a real server.

Onboarding a new QA (2 commands)

No cloning, no building — the package is on npm. On each machine (needs Node.js 18+ and a host):

npm i -g @hassanjamal/api-mcp          # install once
claude mcp add -s user api-mcp -- api-mcp   # register for all projects

Verify with claude mcp list → ✔ Connected. Then open an app folder and either use the /qa-audit slash command or ask in natural language. To update later: npm i -g @hassanjamal/api-mcp@latest.

Notes & limits

• Detection is heuristic (regex-based). It finds string-literal paths; fully dynamic URLs built from variables may be partially normalized (${expr} → {param}).

• Generated request bodies are placeholders — refine them via sampleValues in config for endpoints with strict validation.

• The executor sends real requests. Point it at a dev/staging server, not production.