Supports OpenAPI/Swagger specification discovery and can automatically generate tools from OpenAPI definitions to interact with REST APIs
Any-API MCP Server Template
A minimal, configurable Model Context Protocol (MCP) server you can use to adapt any HTTP API into an MCP toolset. It focuses on safety, clarity, and fast onboarding.
What You Get
- Generic HTTP tools:
api_probe
,api_get
,api_post
,api_put
,api_delete
- Pluggable auth (header, bearer, basic, query param)
- Safe defaults: retries for GET only, rate-limit awareness (Retry-After), STDERR logging with redaction
- Zero-boilerplate startup via STDIO (MCP)
- TypeScript, strict mode, ESM
Quick Start
- Create a new repo and copy this template directory:
- Repo name suggestion:
mcp-any-api
- Copy
templates/any-api-mcp/*
into the new repo root
- Install and build
- Configure environment (two simple options)
Option A — API key/token you already have:
Create
.env.local
(auto-loaded by scripts) with your API details:
Option B — OAuth 2.0 (automated helpers):
Client Credentials (service-to-service):
This writes AUTH_MODE/AUTH_TOKEN into .env.local
.
Device Code (user sign-in on a second device):
Follow the printed verification URL and code. Upon success, the script updates .env.local
.
- Add to your MCP client (example Claude Desktop)
Tools
api_probe
(safe):- Inputs:
path
(string),method
(string), optionalheaders
(record) - Executes a single request and returns status, content-type, body preview (first N bytes)
- Inputs:
api_get
(safe):- Inputs:
path
, optionalquery
(record), optionalheaders
- Retries on
429/502/503/504
with backoff; honorsRetry-After
- Inputs:
api_post
(guarded),api_put
(guarded),api_delete
(guarded):- Inputs:
path
, optionalpayload
(any), optionalheaders
- DELETE supports optional payload if API expects a body
- Inputs:
All tools auto-join API_BASE
with path
and attach auth based on AUTH_MODE
.
Auth Modes
none
: no auth headerbearer
:Authorization: Bearer <AUTH_TOKEN>
header
:<AUTH_HEADER>: <AUTH_TOKEN>
basic
:Authorization: Basic <AUTH_TOKEN>
(you provide base64)query
: appends?<AUTH_QUERY_KEY>=<AUTH_TOKEN>
(or&
when query exists)
Rate Limiting
- GETs retry on
429/502/503/504
using exponential backoff with jitter Retry-After
header is honored when present- Scripts accept
PROBE_DELAY_MS
to pace probes
Examples
Probe a path safely:
GET with query:
POST (guarded):
Customizing
- Add typed, domain-specific tools by creating new handlers in
src/server.ts
- Keep
ALLOW_DESTRUCTIVE=false
until you’re ready to allow writes - To support OAuth2 flows, fetch tokens outside the server and set
AUTH_MODE=bearer
withAUTH_TOKEN
Scripts
npm run validate:endpoints
(safe): probes a set of paths/methods via GET/OPTIONS; pacing + Retry-After; dynamic delay adaptationnpm run probe:get
(safe): throttled GET probe for a given listnpm run discover:openapi
(safe): tries common OpenAPI/Swagger URLs, lists endpoints/methods, and saves raw specnpm run scan:wordlist
(safe): OPTIONS-scan using a small default wordlist or a provided file; dynamic delay adaptationnpm run inventory:api
(safe): one-command inventory; tries OpenAPI first, then wordlist; writes JSON toreports/
npm run openapi:to:tools
(safe): converts an OpenAPI JSON file totools.json
for dynamic tool registrationnpm run scan:to:tools
(safe): converts a wordlist scan report totools.json
npm run oauth2:client
/npm run oauth2:device
: obtain OAuth tokens and update.env.local
Environment knobs:
PROBE_DELAY_MS
: pacing between requests (default 800–1500ms)OUTPUT
/OUTPUT_DIR
: where to save reportsWORDLIST
: path to a custom wordlist (forscan:wordlist
)
All scripts auto-load .env.local
.
Dynamic Tools (No Code Changes)
This server auto-registers tools from tools.json
(if present in the working directory). You can generate tools.json
from discovery output:
From OpenAPI:
From wordlist scan:
Once tools.json
exists, restart the server and the generated tools are available automatically. GET tools are safe; mutating tools are guarded (require ALLOW_DESTRUCTIVE=true
).
Example: Hexnode API
Use the provided example tools file and Hexnode credentials:
- Copy example to working tools file
- Configure Hexnode env in
.env.local
(header auth)
- Start the server
Note: Some Hexnode tenants use singular policy paths (/policy/…
) and others plural (/policies/…
). The example includes both; use whichever works for your tenant or remove non-applicable entries from tools.json
.
File Layout
src/server.ts
: MCP entrypointsrc/lib/*.ts
: helpers (qs, retry, logger)scripts/*
: verification probesdist/*
: compiled output
License
Add your preferred license before public release.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A configurable MCP server that adapts any HTTP API into an MCP toolset with generic HTTP tools (GET, POST, PUT, DELETE) and pluggable authentication. Includes API discovery scripts and supports dynamic tool generation from OpenAPI specs or wordlist scans.