OpenAPI MCP Server

An MCP (Model Context Protocol) server that dynamically generates tools from any OpenAPI 3.x specification. Point it at a spec file or URL and it creates one MCP tool per API operation — no code generation, no AI, pure spec-driven mapping.

How it works

OpenAPI spec (file or URL)
  → parse & resolve $refs (swagger-parser)
  → filter operations (optional include/exclude rules)
  → for each operation:
      → derive tool name from operationId or method+path
      → merge path/query/header params + request body into a single JSON Schema
      → map HTTP method to MCP tool annotations (readOnly, destructive, idempotent)
      → register as an MCP tool with a call handler that makes the actual HTTP request
  → start MCP server over stdio

Features

Any OpenAPI 3.0.x / 3.1.x spec — file path or URL
Smart tool naming — uses operationId when available, falls back to method_path pattern
MCP tool annotations — automatically sets readOnlyHint, destructiveHint, idempotentHint based on HTTP method
Schema merging — path, query, header params and request body flattened into one input schema
Full schema support — objects, arrays, allOf, oneOf, anyOf, enums, formats, nested structures
Auth strategies — Bearer, Basic, API Key (header or query), or none
Operation filtering — include/exclude by path glob, HTTP method, tag, or operationId
Security hardening — response sanitization with cryptographic boundary markers (prompt injection defense), response truncation, rate limiting
Environment variable interpolation — ${API_TOKEN} in CLI args or config files

Prerequisites

Java 21 or later
Maven 3.8+ (to build from source)

Quick start

1. Build

git clone https://github.com/wrxck/openapi-mcp.git
cd openapi-mcp
mvn clean package -DskipTests

This produces target/openapi-mcp-1.0.0.jar — a self-contained executable JAR.

2. Register with Claude Code

claude mcp add --scope user --transport stdio openapi-petstore -- \
  java -jar /path/to/openapi-mcp-1.0.0.jar \
  --spec https://petstore3.swagger.io/api/v3/openapi.json

3. Use

> What pets are available in the store?
> Create a new pet named "Buddy" with tag "dog"
> Get the store inventory

Configuration

CLI arguments

# Minimal — just a spec
java -jar openapi-mcp.jar --spec petstore.yaml

# With auth
java -jar openapi-mcp.jar --spec https://api.example.com/openapi.json \
    --auth-type bearer --auth-token '${API_TOKEN}'

# With API key
java -jar openapi-mcp.jar --spec spec.yaml \
    --auth-type api-key-header --auth-header-name X-API-Key --auth-token 'my-key'

# Rate limiting and timeouts
java -jar openapi-mcp.jar --spec spec.yaml \
    --max-requests-per-minute 30 --request-timeout 15

| Flag | Description | Default | |------|-------------|---------| | --spec | OpenAPI spec file path or URL | (required) | | --config | JSON config file (see below) | | | --auth-type | none, bearer, basic, api-key-header, api-key-query | none | | --auth-token | Auth token/credentials (supports ${ENV_VAR}) | | | --auth-header-name | Custom header name for api-key-header auth | X-API-Key | | --auth-query-param | Query param name for api-key-query auth | api_key | | --server-name | MCP server name | openapi-mcp | | --server-version | MCP server version | 1.0.0 | | --max-requests-per-minute | Rate limit | 60 | | --max-response-length | Truncate responses beyond this length | 50000 | | --connect-timeout | Connection timeout in seconds | 10 | | --request-timeout | Request timeout in seconds | 30 |

JSON config file

For complex setups with filtering:

{
    "spec": "https://api.example.com/openapi.json",
    "authType": "bearer",
    "authToken": "${API_TOKEN}",
    "includeMethods": ["GET", "POST"],
    "excludeTags": ["admin", "internal"],
    "excludePaths": ["/debug/**"],
    "maxRequestsPerMinute": 30,
    "serverName": "my-api"
}

java -jar openapi-mcp.jar --config config.json

Tool annotations

Every generated tool includes MCP annotations based on the HTTP method:

| HTTP Method | readOnlyHint | destructiveHint | idempotentHint | |-------------|:---:|:---:|:---:| | GET, HEAD, OPTIONS | true | false | true | | POST | false | false | false | | PUT | false | false | true | | PATCH | false | false | false | | DELETE | false | true | true |

This means Claude will treat DELETE operations with appropriate caution and won't hesitate to call GET endpoints for information gathering.

Security

Response sanitization — All API responses are wrapped in unique cryptographic boundary markers with instructions to treat the content as untrusted data. This defends against prompt injection via API responses.
Response truncation — Responses are truncated at a configurable limit (default 50k chars) to prevent context overflow.
Rate limiting — Sliding window rate limiter prevents excessive API calls (default 60/minute).
Timeouts — Configurable connect timeout (10s) and request timeout (30s) prevent hanging connections.

Building from source

mvn clean verify

This compiles, runs all 114 tests, and produces the shaded JAR.

Project structure

src/main/java/com/openapi/mcp/
├── OpenApiMcpServer.java       # Entry point, CLI, server bootstrap
├── ServerConfig.java           # CLI args, JSON config, env var interpolation
├── SpecLoader.java             # swagger-parser wrapper
├── ToolGenerator.java          # Orchestrates tool generation from OpenAPI operations
├── ToolNaming.java             # operationId sanitization, method+path fallback
├── SchemaConverter.java        # OpenAPI Schema → JSON Schema
├── InputSchemaBuilder.java     # Merge params + body into single input schema
├── ToolAnnotationMapper.java   # HTTP method → MCP tool annotations
├── HttpApiClient.java          # Execute HTTP requests to target API
├── RequestBuilder.java         # Build HTTP requests from operation metadata
├── AuthProvider.java           # Auth interface
├── AuthProviders.java          # Bearer, Basic, API Key, None implementations
├── OperationFilter.java        # Include/exclude by path, method, tag, operationId
├── ContentSanitizer.java       # Prompt injection defense (boundary markers)
├── ResultHelper.java           # MCP result formatting
└── RateLimiter.java            # Sliding window rate limiter

License

MIT

MCP Servers