The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Rest API MCP listing page.
A Model Context Protocol (MCP) server for authenticated REST APIs.
Drop it into any project, point it at your API, and let AI agents call endpoints — with auto-login, 2FA support, Swagger spec fetch, and fuzzy endpoint search — all without writing a single line of auth code.
| Capability | Description |
|---|---|
| Auto-login | Logs in automatically before every request; re-logins when token expires |
| Token caching | 20-second TTL cache — survives rapid sequential calls |
| Auto-discovery | Finds the login endpoint by scanning the Swagger spec (no config needed) |
| Auto token detection | Tries 9 common token paths (data.access_token, accessToken, token, …) |
| AI-driven token detection | inspect_login tool exposes raw responses + heuristic suggestions so the AI can pick the exact token path |
| 2FA / OTP support | Two-step auth: login → verify-otp, session identifiers forwarded automatically |
| Custom session fields | Override hardcoded session candidates via verify_session_fields in request() |
| Extra login fields | source, userRole, channel, device_id — any field, via JSON env var |
| Fuzzy endpoint search | Find endpoints by keyword across path, summary, description, tags, operationId |
| Swagger spec fetch | Retrieve and inspect the full OpenAPI spec |
| SSL bypass | Optional for staging/dev environments with self-signed certs |
| Response truncation | Configurable size limit to keep responses in context |
No installation needed. Add this to your project's .vscode/mcp.json and VS Code will download and run the package automatically:
This always uses the latest published version from npm. See VS Code mcp.json Examples for a full config.
Then point VS Code at the local build:
Add this to your project's .vscode/mcp.json:
That's it. The agent can now:
All configuration is done via environment variables in mcp.json. No code changes required.
| Variable | Description |
|---|---|
REST_BASE_URL | Base URL of the API (no trailing slash) |
API_EMAIL | Login email |
API_PASSWORD | Login password |
| Variable | Description |
|---|---|
API_SWAGGER_URL | OpenAPI/Swagger JSON URL — enables fetch_spec, search_endpoints, and auto-login-endpoint discovery |
See Environment Variables Reference for the full list.
search_endpointsFuzzy-search the API spec by keyword. Returns matching endpoints with method, path, summary, tags, and required parameters. Use this before request when you don't know the exact path.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
query | string | ✅ | Keywords to search for |
limit | number | ❌ | Max results (default: 10) |
Example — Find order-related endpoints:
Response:
describe_endpointReturns the full OpenAPI schema for a single endpoint: parameters, request body schema (with types, required flags, enums, examples), response schemas, and a generated example request body. Use this before request() when you need to know exactly what fields to include in the body or what response shape to expect.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
method | string | ✅ | GET, POST, PUT, PATCH, DELETE |
endpoint | string | ✅ | Path relative to REST_BASE_URL, e.g. /inspections |
Example — Inspect a POST endpoint before calling it:
Response:
The AI can now call request() with the exact body shape, no guessing required.
requestMake an authenticated API call. Handles login automatically — re-logins transparently if the token is expired.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
method | string | ✅ | GET, POST, PUT, PATCH, DELETE |
endpoint | string | ✅ | Path relative to REST_BASE_URL, e.g. /users/profile |
body | object | ❌ | Request body for POST/PUT/PATCH |
headers | object | ❌ | Extra headers to merge |
skip_auth | boolean | ❌ | Set true to skip the Authorization header |
token_path | string | ❌ | Dot-notation path to the token in the login/verify response (e.g. data.result.accessToken). Overrides auto-detection and is cached for re-logins. |
verify_session_fields | object | ❌ | Map of verify-body field names → dot-notation paths in the step-1 login response. Example: {"sessionId": "data.result.sessionId"}. Overrides hardcoded candidates and is cached for re-logins. |
Response shape:
login_datacontains the full login response — useful for IDs likeuserId,orgId,tenantIdreturned at login that you need for subsequent requests.
Example — GET current user profile:
Example — POST with filters:
Example — PATCH to update a resource:
Example — Public endpoint (no auth):
Example — Custom token path (when auto-detection fails):
Example — Custom 2FA session fields:
inspect_loginPerforms the login flow (and optional 2FA verify) and returns the raw server responses without extracting a token. Also returns heuristic suggestions for:
Use this when auto-detection fails so the AI can identify the correct token_path and verify_session_fields to pass to request().
No input required.
Example — when request() fails with "Could not find token":
Response:
Then call request() with the AI-discovered path:
The server caches the AI-provided token_path and verify_session_fields so re-logins (after token expiry) use them automatically.
fetch_specFetch the full OpenAPI/Swagger JSON spec for schema inspection, DTO discovery, or understanding available endpoints.
Input:
| Field | Type | Required | Description |
|---|---|---|---|
url | string | ❌ | Override spec URL. Falls back to API_SWAGGER_URL env var |
Example:
Returns the raw OpenAPI JSON (truncated to REST_RESPONSE_SIZE_LIMIT if large).
The most common case — email + password, token returned directly.
The server auto-discovers the login endpoint by scanning the Swagger spec for the first POST path containing "login". Override if needed:
Some APIs require fields beyond email and password in the login request body — for example a role to specify what type of user is logging in, a source to indicate which client platform is making the request, a channel, a tenantId, etc.
Set API_LOGIN_CREDENTIALS to a JSON object string containing any extra fields you need. They are merged into the login POST body alongside email and password:
What gets sent to the login endpoint:
Multiple extra fields work the same way:
What gets sent:
Note: The field names are entirely up to your API. Check its Swagger spec or docs to see what the login endpoint accepts.
Some APIs require a second verification step after the initial login — the server returns a one-time code to the user's email or phone, and you must submit it to a separate endpoint to receive the actual JWT.
Flow:
The three env vars that drive this:
API_VERIFY_ENDPOINT — The path of the second step. When this is set, the server automatically performs both steps before attaching a token to your request.
API_OTP — The OTP value to submit. For staging environments this is usually a fixed test code provided by the API team. For production you'd need to retrieve the live code from your email and set it here.
Session carry-forward — Session identifiers returned by login step 1 (e.g. session_token, requestId, temp_token, nonce, transactionId) are automatically detected and forwarded to the verify endpoint. You do not need to configure this manually.
The full body sent to the verify endpoint looks like:
API_VERIFY_CREDENTIALS — If your verify endpoint requires extra fields that aren't session identifiers or the OTP, add them here:
What gets sent:
Run multiple independent server instances — one per API — in the same mcp.json. Each instance runs its own auth session, token cache, and spec cache independently.
In this example, shop-api uses a simple role-based login and analytics-api uses 2FA:
When auto-detection fails:
| Variable | Required | Default | Description |
|---|---|---|---|
REST_BASE_URL | ✅ | — | Base API URL, no trailing slash |
API_EMAIL | ✅* | — | Login email (*required for authenticated endpoints) |
API_PASSWORD | ✅* | — | Login password |
API_SWAGGER_URL | — | — | OpenAPI JSON URL for fetch_spec, search_endpoints, and login auto-discovery |
API_LOGIN_ENDPOINT | — | auto-discovered | Override login path, e.g. /auth/sign-in |
API_LOGIN_CREDENTIALS | — | — | JSON object of extra fields merged into the login POST body alongside email/password. Use for role, source, tenantId, etc. Example: {"role":"admin"} |
API_VERIFY_ENDPOINT | — | — | Path of the 2FA/OTP verify step. Setting this enables two-step auth. Example: /auth/verify-otp |
API_OTP | — | — | The OTP code to submit to API_VERIFY_ENDPOINT. On staging this is typically a fixed test code. |
API_VERIFY_CREDENTIALS | — | — | JSON object of extra fields merged into the verify POST body, beyond the auto-carried session identifiers and OTP. Example: {"client_id":"web-app"} |
API_TOKEN_PATH | — | auto-detected | Dot-path to token in login/verify response, e.g. data.access_token |
REST_ENABLE_SSL_VERIFY | — | true | Set false to skip TLS cert validation (dev/staging only) |
REST_RESPONSE_SIZE_LIMIT | — | 100000 | Max response characters before truncation |
Auto-detected token paths (tried in order):
data.access_token · access_token · data.token · token · data.accessToken · accessToken · data.data.access_token · result.access_token · result.token
If none match, use inspect_login() to discover the correct path and pass it via token_path.
Auto-forwarded session fields (2FA step 1 → step 2):
session_token · sessionToken · session · request_id · requestId · temp_token · tempToken · verification_token · verificationToken · challenge · nonce · transaction_id · transactionId
Override these via verify_session_fields when the API uses non-standard session field names.
Login failed: Could not find token
The login response uses an unusual token path. Use inspect_login() to see the raw response and heuristic suggestions, then pass the correct path to request():
Alternatively, set API_TOKEN_PATH explicitly in env:
2FA verify fails with 401
The verify endpoint may need the OTP as a different field name. Use API_VERIFY_CREDENTIALS:
And leave API_OTP unset if the field name isn't otp.
search_endpoints returns no matches
API_SWAGGER_URL is set and reachable"inventory" instead of "getInventory"fetch_spec to checkSSL errors on staging
Response truncated
Increase the limit:
MIT