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

1. 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

2. Install and build

3. 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.

5. Add to your MCP client (example Claude Desktop)

Tools

• api_probe (safe):

  • Inputs: path (string), method (string), optional headers (record)

  • Executes a single request and returns status, content-type, body preview (first N bytes)

• api_get (safe):

  • Inputs: path, optional query (record), optional headers

  • Retries on 429/502/503/504 with backoff; honors Retry-After

• api_post (guarded), api_put (guarded), api_delete (guarded):

  • Inputs: path, optional payload (any), optional headers

  • DELETE supports optional payload if API expects a body

All tools auto-join API_BASE with path and attach auth based on AUTH_MODE.

Auth Modes

• none: no auth header

• bearer: 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 with AUTH_TOKEN

Scripts

• npm run validate:endpoints (safe): probes a set of paths/methods via GET/OPTIONS; pacing + Retry-After; dynamic delay adaptation

• npm run probe:get (safe): throttled GET probe for a given list

• npm run discover:openapi (safe): tries common OpenAPI/Swagger URLs, lists endpoints/methods, and saves raw spec

• npm run scan:wordlist (safe): OPTIONS-scan using a small default wordlist or a provided file; dynamic delay adaptation

• npm run inventory:api (safe): one-command inventory; tries OpenAPI first, then wordlist; writes JSON to reports/

• npm run openapi:to:tools (safe): converts an OpenAPI JSON file to tools.json for dynamic tool registration

• npm run scan:to:tools (safe): converts a wordlist scan report to tools.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 reports

• WORDLIST: path to a custom wordlist (for scan: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:

1. Copy example to working tools file

2. Configure Hexnode env in .env.local (header auth)

3. 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 entrypoint

• src/lib/*.ts: helpers (qs, retry, logger)

• scripts/*: verification probes

• dist/*: compiled output

License

Add your preferred license before public release.