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

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:

{
  "command": "npx",
  "args": ["-y", "rest-api-mcp"]
}

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)

git clone https://github.com/Muhammed-AbdelGhany/rest_api_mcp
cd rest_api_mcp
npm install && npm run build

Then point VS Code at the local build:

{
  "command": "node",
  "args": ["/path/to/rest_api_mcp/build/index.js"]
}

Quick Start

Add this to your project's .vscode/mcp.json:

{
  "servers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "rest-api-mcp"],
      "env": {
        "REST_BASE_URL": "https://api.example.com/api/v1",
        "API_EMAIL": "user@example.com",
        "API_PASSWORD": "yourpassword",
        "API_SWAGGER_URL": "https://api.example.com/docs-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

Strongly recommended

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:

Example — Find order-related endpoints:

search_endpoints("orders list customer")

Response:

Found 6 match(es) for "orders list customer", showing top 5:

1. GET /customers/{id}/orders
   Summary: List all orders for a customer
   Tags: Orders, Customers
   Required params: path:id

2. GET /orders
   Summary: List orders with optional filters
   Tags: Orders
   Required params: query:status, query:page

3. POST /orders/search
   Summary: Search orders by multiple criteria
   Tags: Orders
   Required params: body
...

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:

Example — Inspect a POST endpoint before calling it:

describe_endpoint("POST", "/pharmacy/add-manager")

Response:

{
  "method": "POST",
  "path": "/pharmacy/add-manager",
  "summary": "Add a manager to a pharmacy",
  "parameters": [
    { "name": "pharmacyId", "in": "path", "required": true, "type": "string" }
  ],
  "requestBody": {
    "contentType": "application/json",
    "schema": {
      "type": "object",
      "properties": {
        "first_name": { "type": "string", "required": true },
        "email": { "type": "string", "required": true },
        "gender": { "type": "string", "enum": ["male", "female"], "required": true },
        "start_date": { "type": "string", "format": "date-time", "required": true }
      }
    },
    "example": {
      "first_name": "First name",
      "email": "manager@example.com",
      "gender": "male",
      "start_date": "2026-05-04T12:00:00Z"
    }
  },
  "responses": {
    "201": {
      "description": "Manager added successfully",
      "schema": { "type": "object", "properties": { "id": { "type": "number" } } },
      "example": { "id": 42 }
    }
  }
}

The AI can now call request() with the exact body shape, no guessing required.

request

Make an authenticated API call. Handles login automatically — re-logins transparently if the token is expired.

Input:

Response shape:

{
  "status": 200,
  "statusText": "OK",
  "timing_ms": 312,
  "login_data": { ... },
  "response": { ... }
}

login_data contains the full login response — useful for IDs like userId, orgId, tenantId returned at login that you need for subsequent requests.

Example — GET current user profile:

request("GET", "/users/me")

Example — POST with filters:

request("POST", "/orders/search", {
  "status": "pending",
  "from": "2025-01-01",
  "limit": 20
})

Example — PATCH to update a resource:

request("PATCH", "/products/42", {
  "price": 9.99,
  "inStock": true
})

Example — Public endpoint (no auth):

request("GET", "/health", skip_auth=true)

Example — Custom token path (when auto-detection fails):

request("GET", "/orders", token_path="result.data.jwtToken")

Example — Custom 2FA session fields:

request("GET", "/orders",
  token_path="data.result.accessToken",
  verify_session_fields={"sessionId": "data.result.sessionId", "requestToken": "data.result.requestToken"}
)

inspect_login

Performs the login flow (and optional 2FA verify) and returns the raw server responses without extracting a token. Also returns heuristic suggestions for:

• Token paths (fields that look like JWTs or long auth strings)
• Session fields (fields that look like session identifiers for 2FA verify)

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

inspect_login()

Response: