MCP Server for OpenAPI-Driven AI Assistants

Overview

This MCP (Model Context Protocol) server converts OpenAPI (Swagger) specifications into MCP-compatible tools so AI assistants can discover and invoke REST APIs through a consistent protocol. Instead of hand-coding tool descriptions or adapters for each API, you feed the server an OpenAPI document (local file or URL) and it exposes a standardized set of MCP endpoints that describe available operations and proxy requests to the underlying API.

That makes it easier to integrate existing HTTP services with LLM-based assistants, testing frameworks, or orchestration systems that understand MCP. The server can handle common patterns like path/parameter mapping, authentication injection, and response normalization so the assistant sees a consistent tool surface across many APIs.

Features

• Generate MCP tool manifests directly from OpenAPI / Swagger specs
• Host tool metadata and invocation endpoints that follow the MCP pattern
• Proxy requests to the upstream API with support for API keys, bearer tokens, and header mapping
• Support local files or remote OpenAPI URLs; hot-reload on spec changes during development
• Simple configuration via environment variables or JSON config
• Docker-friendly for easy deployment and reproducible environments
• Logging, CORS, and basic request validation to reduce runtime errors
• Pluggable hooks to transform requests and responses (customize parameter/format conversions)

Installation / Configuration

Two common ways to run the server: from source (node/npm) or using Docker.

From source (GitHub):

# clone repository
git clone https://github.com/zaizaizhao/mcp-swagger-server.git
cd mcp-swagger-server

# install dependencies (Node.js)
npm install

# copy example env and edit
cp .env.example .env
# edit .env to set OPENAPI_URL, PORT, AUTH_* etc.

# start in development mode
npm run dev

# or production
npm start

Docker:

# build
docker build -t mcp-swagger-server .

# run (example)
docker run -e OPENAPI_URL=https://api.example.com/openapi.json \
  -e PORT=8080 \
  -p 8080:8080 \
  mcp-swagger-server

Example environment variables / config keys (names may vary in the repo):

PORT=8080
OPENAPI_URL=https://api.example.com/openapi.json
API_KEY_HEADER=X-Api-Key
API_KEY_VALUE=secret123
CORS_ORIGINS=*
AUTH_STRATEGY=header   # 'header' | 'bearer' | 'none'

Alternatively use a JSON config file:

{
  "port": 8080,
  "openapi": "specs/petstore.yaml",
  "auth": {
    "strategy": "header",
    "headerName": "X-Api-Key",
    "value": "${API_KEY_VALUE}"
  },
  "cors": "*"
}

Available Tools / Resources

When the server runs, it exposes a predictable set of MCP-style endpoints so assistants and orchestration layers can discover tools and call them. Typical endpoints (defaults — check your server config for exact paths):

• GET /mcp/tools
  • Returns a list of tools generated from the OpenAPI operations
• GET /mcp/tools/{toolId}
  • Returns tool metadata (name, description, parameters, input/output schemas)
• POST /mcp/tools/{toolId}/invoke
  • Invoke the underlying API operation. Request body contains structured input according to the tool metadata.
• GET /health
  • Basic health/status check for orchestration and monitoring

These endpoints are designed to mirror MCP discovery and invocation flows: a client fetches metadata, prepares a structured input, and posts an invocation; the server validates and proxies the call to the upstream API.

Use Cases

1. Expose third-party REST APIs to an LLM assistant

   • Example: Point the server at the GitHub OpenAPI spec URL. The server generates tools for “list repos”, “create issue”, etc. The assistant discovers the “createIssue” tool metadata and calls POST /mcp/tools/createIssue/invoke with parameters like owner, repo, title, and body. The server applies authentication and forwards the request to the real GitHub API.

2. Wrap internal microservices for secure assistant access

   • Example: Your company has an internal CRM API described with OpenAPI. Run the MCP server inside your VPC, configure API-key injection or an internal bearer token, and expose only the MCP endpoints to your assistant infrastructure. The assistant receives consistent tool manifests and cannot call arbitrary internal endpoints directly.

3. Rapid prototyping and testing of tool-assisted workflows

   • Use a local OpenAPI file with mocked responses. The MCP server will generate tools you can invoke from an assistant or automated test harness to validate tool-driven conversation flows without hitting production systems.

4. Translate mismatched parameter models

   • Many APIs expect complex paths, headers, or query parameter combinations. The server can normalize these into simple tool parameters (e.g., flatten nested body fields) and perform necessary encoding and header injection at invocation time.

Quick example: invoking a tool

Assuming a generated tool named “listPets”:

curl -X POST "http://localhost:8080/mcp/tools/listPets/invoke" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10, "status": "available"}'

Response is the normalized JSON payload returned by the upstream API, optionally wrapped with metadata (status, headers) depending on server configuration.

Notes and next steps

• Check the repo README and configuration files for exact path names and