mcp4openapi/mcp4openapi repository overview

Universal MCP server from OpenAPI 3.x Specification

⁠What this image does

This image runs the mcp4openapi server: it takes an OpenAPI 3.x specification and an MCP profile and exposes the described operations as MCP tools (and optional composite workflows). It can run as a stdio MCP server or as an HTTP server, with optional OAuth and multi-auth support, rate-limited HTTP transport, metrics, and structured logging.

⁠Key features

• Any OpenAPI 3.x spec: consume YAML/JSON specs and validate them on startup.
• Profiles & tooling: use MCP profiles to select, group and rename operations into meaningful tools (with warnings for awkward naming).
• Composite actions: define DAG/composite workflows that call multiple API operations in sequence or in parallel.
• Multiple transports: stdio (MCP native) and HTTP server mode, with streaming support.
• Auth & security: token auth, OAuth flows, multi-auth profiles, origin whitelisting, and optional token validation helpers.
• Observability: structured logging, optional Prometheus metrics endpoint, basic health endpoint.
• Batteries included: written in TypeScript, fully tested, with profile/schema validators and OpenAPI parser included.

⁠Who should use this image

• Developers who want to expose APIs as MCP tools from OpenAPI instead of hand-writing MCP servers.
• Teams managing multiple APIs and user profiles (admin/developer/readonly) and needing a unified MCP gateway.
• LLM/agent integrations where you want a curated, profiled tool surface rather than exposing hundreds of raw operations.

⁠Quick start

docker pull mcp4openapi/mcp4openapi

Create a .env file (or use environment variables) with at least:

# Required
OPENAPI_SPEC_PATH=/data/openapi.yaml
MCP_PROFILE_PATH=/data/profile.json

# Auth example (optional, depends on your profile)
API_TOKEN=your_secret_token

# Transport: 'stdio' or 'http'
MCP_TRANSPORT=http
MCP_PORT=3003

# CORS / origins for HTTP mode
ALLOWED_ORIGINS=*

# Logging & metrics
LOG_LEVEL=info
METRICS_ENABLED=false

Run the container (HTTP mode example):

docker run \
  --rm \
  -p 3003:3003 \
  --env-file .env \
  -v /absolute/path/to/config:/data \
  mcp4openapi/mcp4openapi

Health check:

curl http://localhost:3003/health

To use it as an MCP stdio server, set MCP_TRANSPORT=stdio and configure your MCP-compatible client to execute the container with stdio wiring.

⁠Configuration & usage notes

• OPENAPI_SPEC_PATH: path inside the container to your OpenAPI 3.x YAML/JSON. Mount it via -v.
• MCP_PROFILE_PATH: MCP profile JSON describing which operations and composites to expose (see profiles/ and docs in the repo).
• In http transport mode the server exposes HTTP endpoints (including health and, if enabled, /metrics in Prometheus format).
• In stdio mode it behaves as a standard MCP server for local tools/agents.
• For production, secure HTTP mode (HTTPS/TLS at the proxy, restrict ALLOWED_ORIGINS, configure strong auth according to your profile).

⁠License & source

MIT License. Full documentation, example profiles and environment options are in the GitHub repository:
https://github.com/davidruzicka/mcp4openapi⁠