openapi-mcp

OpenAPI 3 → MCP server. Turn a REST API contract into MCP tools, resources, and prompts for LLM agents.

Zero-config out of the box: a bundled demo spec (examples/demo/openapi.json) is used when no OpenAPI env vars are set.

Quick start (60 seconds)

cd openapi-mcp
npm install
npm run generate
npm run serve

Connect your MCP client to the stdio transport (npm run serve). The server exposes tools such as item.list, item.getById, and item.create from the demo spec.

For HTTP mode:

copy .env.example .env
npm run serve:http

Send requests to http://127.0.0.1:3334/mcp with:

x-mcp-admission-key — admits the caller to the MCP transport
x-api-key — upstream REST API identity (forwarded to the backend)

Configure your own API

Single local spec

$env:MCP_OPENAPI_PATH = "path/to/your/openapi.json"
$env:MCP_BASE_URL = "https://api.example.com"
$env:MCP_API_KEY = "your-api-key"
npm run generate
npm run serve

Multiple specs

$env:MCP_OPENAPI_SOURCES = '[{"id":"billing","displayName":"Billing API","kind":"file","location":"specs/billing.json"},{"id":"users","displayName":"Users API","kind":"remote","location":"https://api.example.com/users/openapi.json"}]'
npm run generate

When more than one spec is loaded, tool names are namespaced (billing.listInvoices, users.getProfile, …).

Remote spec

{
  "id": "petstore",
  "displayName": "Petstore",
  "kind": "remote",
  "location": "https://example.com/openapi.json"
}

Transports

| Command | Transport | Notes | | --- | --- | --- | | npm run serve | stdio | Default for local MCP clients | | npm run serve:http | HTTP stateless | One request/response per MCP call | | npm run serve:http:stateful | HTTP stateful | Session via Mcp-Session-Id header |

Health check: GET /healthz (configurable via MCP_HTTP_HEALTH_PATH).

Environment variables

| Variable | Purpose | Default | | --- | --- | --- | | MCP_BASE_URL | Upstream REST API base URL | http://127.0.0.1:4010 | | MCP_API_KEY | Stdio/runtime upstream API key | unset | | MCP_OPENAPI_PATH | Single local spec override | unset (uses bundled demo) | | MCP_OPENAPI_SOURCES | Multi-spec JSON array | unset (uses bundled demo) | | MCP_ADMISSION_HEADER | HTTP admission header | x-mcp-admission-key | | MCP_UPSTREAM_API_KEY_HEADER | Upstream API key header | x-api-key | | MCP_HTTP_KEYS | Allowed admission keys (JSON array or comma-separated) | dev UUID in .env.example | | MCP_HTTP_MODE | stateless or stateful | stateless | | MCP_HTTP_HOST | HTTP listener host | 127.0.0.1 | | MCP_HTTP_PORT | HTTP listener port | 3334 | | MCP_HTTP_PATH | MCP endpoint path | /mcp | | MCP_HTTP_HEALTH_PATH | Health endpoint path | /healthz | | MCP_SERVER_NAME | MCP server metadata name | openapi-mcp | | MCP_RESOURCE_URI_SCHEME | Resource URI prefix | openapi-mcp:// | | MCP_USER_AGENT | Upstream User-Agent | openapi-mcp/0.1.0 | | MCP_TIMEOUT_MS | Upstream request timeout | 15000 | | MCP_DEBUG | Verbose request logging | false |

Copy .env.example to .env for local development.

Generation vs runtime

Generate (npm run generate) — loads OpenAPI spec(s), builds an internal IR, and writes manifests under generated/ (tools, resources, prompts, coverage, drift reports).
Serve (npm run serve / serve:http) — loads the generated manifests and proxies tool calls to the upstream REST API.

Re-run generate whenever your OpenAPI contract changes.

Auth model

MCP admission (HTTP only): static keys validated via MCP_HTTP_KEYS and the admission header.
Upstream API key: forwarded per operation based on OpenAPI security schemes. Bearer-only operations are excluded from the MVP tool surface.
Stdio mode: uses MCP_API_KEY from the environment unless overridden per request in HTTP mode.

Scripts

| Script | Description | | --- | --- | | npm run generate | Build manifests from OpenAPI | | npm run build | Compile TypeScript to dist/ | | npm run serve | Stdio MCP server | | npm run serve:http | HTTP stateless MCP server | | npm run serve:http:stateful | HTTP stateful MCP server | | npm run smoke:stdio | Smoke test stdio transport | | npm run smoke:http | Smoke test HTTP transport | | npm run test | Run vitest suite | | npm run verify | generate + build + test |

Programmatic use

import { runGenerationPipeline, loadRuntimeBundle, buildMcpServer, loadRuntimeConfig } from "openapi-mcp";

Exports are also available at openapi-mcp/config and openapi-mcp/generate.

License

MIT

MCP Servers