OpenAPI MCP MCP server for AI agents

openapi-mcp transforms any OpenAPI 3.x specification into an MCP (Model Context Protocol) tool server, making it easy to expose APIs as tools that AI agents and applications can interact with. It validates your OpenAPI spec, generates MCP tools for each operation, and serves them through stdio or HTTP with structured, machine-readable output.

Installation

Prerequisites

Go 1.21+
An OpenAPI 3.x YAML or JSON specification file

Building from Source

# Clone the repository
git clone <repo-url>
cd openapi-mcp

# Build the binaries
make

# This will create:
# - bin/openapi-mcp (main tool)
# - bin/mcp-client (interactive client)

Quick Start

Running the MCP Server

# Basic usage (stdio mode)
bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# With API key
API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# As HTTP server
bin/openapi-mcp --http=:8080 examples/fastly-openapi-mcp.yaml

# Override base URL
bin/openapi-mcp --base-url=https://api.example.com examples/fastly-openapi-mcp.yaml

Using the Interactive Client

# Start the client (connects to openapi-mcp via stdio)
bin/mcp-client bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# Client commands
mcp> list                              # List available tools
mcp> schema <tool-name>                # Show tool schema
mcp> call <tool-name> {arg1: value1}   # Call a tool with arguments
mcp> describe                          # Get full API documentation

Authentication

openapi-mcp supports standard OpenAPI authentication methods:

Command-Line Flags & Environment Variables

# API Key authentication
bin/openapi-mcp --api-key=your_api_key examples/fastly-openapi-mcp.yaml
# or use environment variable
API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# Bearer token / OAuth2
bin/openapi-mcp --bearer-token=your_token examples/fastly-openapi-mcp.yaml
# or use environment variable
BEARER_TOKEN=your_token bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# Basic authentication
bin/openapi-mcp --basic-auth=username:password examples/fastly-openapi-mcp.yaml
# or use environment variable
BASIC_AUTH=username:password bin/openapi-mcp examples/fastly-openapi-mcp.yaml

HTTP Header Authentication (HTTP Mode Only)

When using HTTP mode, you can provide authentication via HTTP headers:

# API Key via headers
curl -H "X-API-Key: your_api_key" http://localhost:8080/mcp -d '...'
curl -H "Api-Key: your_api_key" http://localhost:8080/mcp -d '...'

# Bearer token
curl -H "Authorization: Bearer your_token" http://localhost:8080/mcp -d '...'

# Basic authentication
curl -H "Authorization: Basic base64_credentials" http://localhost:8080/mcp -d '...'

Usage Examples

Integration with AI Code Editors

{
    "fastly": {
        "command": "/opt/bin/openapi-mcp",
        "args": [
            "-api-key",
            "YOUR_API_KEY",
            "/opt/etc/openapi/fastly-openapi-mcp.yaml"
        ]
    }
}

OpenAPI Validation and Linting

# Validate OpenAPI spec for critical issues
bin/openapi-mcp validate examples/fastly-openapi-mcp.yaml

# Comprehensive linting with suggestions
bin/openapi-mcp lint examples/fastly-openapi-mcp.yaml

# Start HTTP validation service
bin/openapi-mcp --http=:8080 validate

# Start HTTP linting service
bin/openapi-mcp --http=:8080 lint

HTTP API for Validation and Linting

With the HTTP service running, you can validate OpenAPI specs via REST API:

# Example request
curl -X POST http://localhost:8080/lint \
  -H "Content-Type: application/json" \
  -d '{"openapi_spec": "..."}'

Dry Run (Preview Tools as JSON)

bin/openapi-mcp --dry-run examples/fastly-openapi-mcp.yaml

Generate Documentation

bin/openapi-mcp --doc=tools.md examples/fastly-openapi-mcp.yaml

Filter Operations

bin/openapi-mcp filter --tag=admin examples/fastly-openapi-mcp.yaml
bin/openapi-mcp filter --include-desc-regex="user|account" examples/fastly-openapi-mcp.yaml
bin/openapi-mcp filter --exclude-desc-regex="deprecated" examples/fastly-openapi-mcp.yaml
bin/openapi-mcp filter --function-list-file=funcs.txt examples/fastly-openapi-mcp.yaml

Print Summary

bin/openapi-mcp --summary --dry-run examples/fastly-openapi-mcp.yaml

Post-Process Schema

bin/openapi-mcp --doc=tools.md --post-hook-cmd='jq . | tee /tmp/filtered.json' examples/fastly-openapi-mcp.yaml

Disable Confirmation for Dangerous Actions

bin/openapi-mcp --no-confirm-dangerous examples/fastly-openapi-mcp.yaml

Command-Line Options

Commands

Command	Description
`validate <spec>`	Validate OpenAPI spec and report critical issues
`lint <spec>`	Comprehensive linting with detailed suggestions for best practices
`filter <spec>`	Output a filtered list of operations as JSON, applying various filters (no server)

Flags

Flag	Environment Variable	Description
`--api-key`	`API_KEY`	API key for authentication
`--bearer-token`	`BEARER_TOKEN`	Bearer token for Authorization header
`--basic-auth`	`BASIC_AUTH`	Basic auth credentials (user:pass)
`--base-url`	`OPENAPI_BASE_URL`	Override base URL for HTTP calls
`--http`	-	Serve MCP over HTTP instead of stdio
`--tag`	`OPENAPI_TAG`	Only include operations with this tag
`--include-desc-regex`	`INCLUDE_DESC_REGEX`	Only include APIs matching regex
`--exclude-desc-regex`	`EXCLUDE_DESC_REGEX`	Exclude APIs matching regex
`--dry-run`	-	Print tool schemas as JSON and exit
`--summary`	-	Print operation count summary
`--doc`	-	Generate documentation file
`--doc-format`	-	Documentation format (markdown or html)
`--post-hook-cmd`	-	Command to post-process schema JSON
`--no-confirm-dangerous`	-	Disable confirmation for dangerous actions
`--extended`	-	Enable human-friendly output
`--function-list-file`	-	Only include operations listed in file

Output Structure

All tool results include a consistent structure for machine readability:

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "api_response",
  "data": {
    // API-specific response data
  },
  "metadata": {
    "status_code": 200,
    "headers": {
      // Response headers
    }
  }
}

For errors, you'll receive:

{
  "OutputFormat": "structured",
  "OutputType": "json",
  "type": "error",
  "error": {
    "code": "validation_error",
    "message": "Invalid parameter",
    "details": {
      "field": "username",
      "reason": "required field missing"
    },
    "suggestions": [
      "Provide a username parameter"
    ]
  }
}

Safety Features

For any operation that performs a PUT, POST, or DELETE, openapi-mcp requires confirmation:

{
  "type": "confirmation_request",
  "confirmation_required": true,
  "message": "This action is irreversible. Proceed?",
  "action": "delete_resource"
}

To proceed, retry the call with:

{
  "original_parameters": {},
  "__confirmed": true
}

This confirmation workflow can be disabled with --no-confirm-dangerous.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "openapi-mcp" '{"command":"openapi-mcp","args":["examples/fastly-openapi-mcp.yaml"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "openapi-mcp": {
            "command": "openapi-mcp",
            "args": [
                "examples/fastly-openapi-mcp.yaml"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "openapi-mcp": {
            "command": "openapi-mcp",
            "args": [
                "examples/fastly-openapi-mcp.yaml"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect