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

1. Generate (npm run generate) — loads OpenAPI spec(s), builds an internal IR, and writes manifests under generated/ (tools, resources, prompts, coverage, drift reports).
2. 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