rest-api-mcp

A lightweight Model Context Protocol (MCP) server that lets LLMs interact with any REST API. It executes HTTP requests and provides optimized response analysis, including automatic TypeScript interface generation from live API responses.

Features

• Full HTTP support — GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
• Smart response truncation — large JSON payloads are intelligently reduced (arrays sliced, structure preserved) instead of being cut mid-string
• TypeScript type generation — automatically derives TypeScript interfaces from API response structures
• Response structure analysis — inspect keys, types, and array lengths without returning the full body
• Field extraction — pull specific fields using dot-notation paths (e.g. data.items[].name)
• Flexible authentication — bearer token resolution chain: project .env.mcp file → MCP config env var → session token
• Custom headers — inject global headers via HEADER_* environment variables
• Zero external runtime dependencies — uses only the MCP SDK and Node.js built-in fetch

Tools

Tool	Description
rest_request	Execute a request and return the full (smart-truncated) response
rest_describe	Execute a request and return the response structure + generated TypeScript interfaces (no full body)
rest_types	Execute a request and return only the generated TypeScript interfaces
rest_extract	Execute a request and extract specific fields by dot-notation paths
rest_set_token	Set a bearer token for the current session

Installation

Prerequisites

• Node.js >= 18.0.0
• pnpm (or npm/yarn)

Build from source

git clone <repository-url>
cd rest-api-mcp
pnpm install
pnpm build

Configure in your MCP client

Add the server to your MCP client configuration (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "rest-api": {
      "command": "node",
      "args": ["/path/to/rest-api-mcp/dist/index.js"],
      "env": {
        "REST_BASE_URL": "https://api.example.com",
        "REST_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Configuration

All configuration is done via environment variables:

Variable	Required	Description
REST_BASE_URL	Yes	Base URL for all API requests (e.g. https://api.example.com/v1)
REST_BEARER_TOKEN	No	Bearer token for authentication
REST_RESPONSE_SIZE_LIMIT	No	Max response size in bytes before smart truncation (default: 50000)
REST_ENV_DIR	No	Additional directory to search for .env.mcp files containing REST_BEARER_TOKEN
HEADER_*	No	Custom headers injected into every request (e.g. HEADER_X_API_KEY=abc sends X-Api-Key: abc)

Authentication

Bearer tokens are resolved in this order (first match wins):

1. Project .env.mcp file — REST_BEARER_TOKEN in a .env.mcp file in the working directory or REST_ENV_DIR. Re-read on every request, so token rotation is supported without restarting the server.
2. MCP config env var — REST_BEARER_TOKEN set in the MCP server configuration.
3. Session token — set at runtime via the rest_set_token tool.

If a 401 or 403 response is received and no token is configured, the server returns an auth hint suggesting resolution steps.

Usage Examples

Basic request

rest_request({ method: "GET", endpoint: "/users" })

With query parameters

rest_request({ method: "GET", endpoint: "/users", query: { page: "1", limit: "10" } })

Generate TypeScript types from an endpoint

rest_types({ method: "GET", endpoint: "/users/1", typeName: "User" })

Describe response structure

rest_describe({ method: "GET", endpoint: "/products", typeName: "ProductList" })

Extract specific fields

rest_extract({ method: "GET", endpoint: "/orders", fields: ["data[].id", "data[].status", "meta.total"] })

Development

# Watch mode with hot reload
pnpm dev

# Build for production
pnpm build

# Run the built server
pnpm start

License

MIT