Muhammed-AbdelGhany/rest_api_mcp

> 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.
---
Table of Contents
- Features
- Installation
- Quick Start
- Configuration
- Tools
- search_endpoints
- describe_endpoint
- request
- fetch_spec
- inspect_login
- Authentication Flows
- Standard login
- Login with extra credentials
- Two-factor authentication (2FA)
- Multi-API Setup
- VS Code mcp.json Examples
- How It Works
- Environment Variables Reference
- Troubleshooting
---
Features
| 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 |
---
Installation
Option A — Use via npx (recommended)
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.
Option B — Use locally (for development / offline)
Then point VS Code at the local build:
---
Quick Start
Add this to your project's .vscode/mcp.json:
That's it. The agent can now:
1. Search for endpoints by keyword
2. Call any endpoint with automatic authentication
3. Fetch the full OpenAPI spec for schema inspection
---
Configuration
All configuration is done via environment variables in mcp.json. No code changes required.
Minimum required
| Variable | Description |
|---|---|
| REST_BASE_URL | Base URL of the API (no trailing slash) |
| API_EMAIL | Login email |
| API_PASSWORD | Login password |
Strongly recommended
| Variable | Description |
|---|---|
| API_SWAGGER_URL | OpenAPI/Swagger JSON URL — enables fetch_spec, search_endpoints, and auto-login-endpoint discovery |
Optional
See Environment Variables Reference for the full list.
---
Tools
search_endpoints
Fuzzy-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_endpoint
Returns 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 |