OpenAPI MCP Server: Connect to OpenAPI APIs

Overview

The OpenAPI MCP Server connects OpenAPI-described APIs to tools and agents that speak the Model Context Protocol (MCP). It reads OpenAPI specs (local file or remote URL), exposes each operation as a discrete tool, and provides a lightweight HTTP interface to let models or orchestration code discover and invoke those tools. This makes it easy to test, query, and automate third‑party or internal REST APIs from LLM-based workflows without hand-coding client wrappers.

For developers, the server streamlines two common tasks: (1) translating an OpenAPI contract into a predictable tool surface that models can call, and (2) handling runtime concerns such as authentication, parameter marshaling, and response normalization. You can run it locally for development, deploy it alongside your services, or containerize it for production usage.

Features

• Automatic tool generation from OpenAPI (v2/v3) specs
• Support for local file or remote OpenAPI URL sources
• Simple HTTP endpoints for spec inspection and tool invocation
• Built-in handling for common auth patterns (API key, bearer token)
• Option to run as a container or as a Node service
• Logging and basic request/response normalization for LLM consumption
• Useful for testing, simulation, and production integrations

Installation / Configuration

Prerequisites: Node.js (>=16) or Docker.

Clone and run locally:

git clone https://github.com/snaggle-ai/openapi-mcp-server.git
cd openapi-mcp-server
npm install
npm run start
# or for development:
npm run dev

Environment variables (common):

# Example .env
PORT=8080
OPENAPI_SPEC_URL=https://api.example.com/openapi.json
OPENAPI_SPEC_PATH=./specs/petstore.yaml   # optional; local file overrides URL
API_AUTH_TYPE=Bearer                      # e.g. "Bearer" or "ApiKey"
API_AUTH_VALUE=sk-...                     # token or key for upstream APIs
LOG_LEVEL=info

Docker:

# Build
docker build -t openapi-mcp-server .

# Run with a remote spec
docker run -p 8080:8080 \
  -e OPENAPI_SPEC_URL="https://api.example.com/openapi.json" \
  -e API_AUTH_TYPE="Bearer" \
  -e API_AUTH_VALUE="sk-..." \
  openapi-mcp-server

Configuration table

The server will prefer a local spec file if OPENAPI_SPEC_PATH is provided; otherwise it will attempt to fetch OPENAPI_SPEC_URL on startup and periodically refresh if configured.

Available Resources

• GitHub repository: https://github.com/snaggle-ai/openapi-mcp-server
• OpenAPI specification: https://swagger.io/specification/
• Model Context Protocol (MCP) reference (concepts): see project docs in the repo
• Examples directory (in repo): sample OpenAPI specs and example requests
• Health and introspection endpoints (typical):
  • GET /health — simple liveness check
  • GET /spec — returns the loaded OpenAPI document
  • GET /tools — lists generated tool operations (operationId, method, path)
  • POST /invoke — invoke a specific operation (see example below)

Note: endpoint paths above are representative. Consult the repo’s documentation for exact routes and payload shapes.

Use Cases

1. Test and prototype APIs with an LLM

   • Run the server locally pointed at your internal OpenAPI file. Use an LLM to compose calls against the generated tools (list available operations, then invoke GET/POST endpoints) so you can prototype agent behaviors without writing client code.

2. Expose third‑party APIs as model-callable tools

   • Point the server at a remote OpenAPI document from a SaaS provider. The server handles