Expose any OpenAPI 3.x API as a robust, agent-friendly MCP tool server in seconds!

openapi-mcp transforms any OpenAPI 3.x specification into a powerful, AI-friendly MCP (Model Context Protocol) tool server. In seconds, it validates your OpenAPI spec, generates MCP tools for each operation, and starts serving through stdio or HTTP with structured, machine-readable output.

• openapi-mcp
  • 📋 Table of Contents
  • ✨ Features
  • 🤖 AI Agent Integration
  • 🔧 Installation
    • Prerequisites
    • Build from Source
  • ⚡ Quick Start
    • 1. Run the MCP Server
    • 2. Use the Interactive Client
  • 🔒 Authentication
  • 🛠️ Usage Examples
    • Integration with AI Code Editors
    • OpenAPI Validation and Linting
      • HTTP API for Validation and Linting
    • Dry Run (Preview Tools as JSON)
    • Generate Documentation
    • Filter Operations by Tag
    • Include/Exclude Operations by Description
    • Print Summary
    • Post-Process Schema with External Command
    • Disable Confirmation for Dangerous Actions
  • 🎮 Command-Line Options
    • Commands
    • Flags
  • 📚 Library Usage
  • 📊 Output Structure
  • 🛡️ Safety Features
  • 📝 Documentation Generation
  • 🙌 Contributing
  • 📄 License

• Instant API to MCP Conversion: Parses any OpenAPI 3.x YAML/JSON spec and generates MCP tools
• Multiple Transport Options: Supports stdio (default) and HTTP server modes
• Complete Parameter Support: Path, query, header, cookie, and body parameters
• Authentication: API key, Bearer token, Basic auth, and OAuth2 support
• Structured Output: All responses have consistent, well-structured formats with type information
• Validation & Linting: Comprehensive OpenAPI validation and linting with actionable suggestions
  • validate command for critical issues (missing operationIds, schema errors)
  • lint command for best practices (summaries, descriptions, tags, parameter recommendations)
• Safety Features: Confirmation required for dangerous operations (PUT/POST/DELETE)
• Documentation: Built-in documentation generation in Markdown or HTML
• AI-Optimized: Unique features specifically designed to enhance AI agent interactions:
  • Consistent output structures with OutputFormat and OutputType for reliable parsing
  • Rich machine-readable schema information with constraints and examples
  • Streamlined, agent-friendly response format with minimal verbosity
  • Intelligent error messages with suggestions for correction
  • Automatic handling of authentication, pagination, and complex data structures
• Interactive Client: Includes an MCP client with readline support and command history
• Flexible Configuration: Environment variables or command-line flags
• CI/Testing Support: Summary options, exit codes, and dry-run mode

openapi-mcp is designed for seamless integration with AI coding agents, LLMs, and automation tools with unique features that set it apart from other API-to-tool converters:

• Structured JSON Responses: Every response includes OutputFormat and OutputType fields for consistent parsing
• Rich Schema Information: All tools provide detailed parameter constraints and examples that help AI agents understand API requirements
• Actionable Error Messages: Validation errors include detailed information and suggestions that guide agents toward correct usage
• Safety Confirmations: Standardized confirmation workflow for dangerous operations prevents unintended consequences
• Self-Describing API: The describe tool provides complete, machine-readable documentation for all operations
• Minimal Verbosity: No redundant warnings or messages to confuse agents—outputs are optimized for machine consumption
• Smart Parameter Handling: Automatic conversion between OpenAPI parameter types and MCP tool parameters
• Contextual Examples: Every tool includes context-aware examples based on the OpenAPI specification
• Intelligent Default Values: Sensible defaults are provided whenever possible to simplify API usage

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

# 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)

# 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

# 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

openapi-mcp supports all standard OpenAPI authentication methods via command-line flags, environment variables, or HTTP headers:

# 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

When using HTTP mode (--http=:8080), you can provide authentication via HTTP headers in your requests:

# 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 '...'

Supported Authentication Headers:

• X-API-Key or Api-Key - for API key authentication
• Authorization: Bearer <token> - for OAuth2/Bearer token authentication
• Authorization: Basic <credentials> - for Basic authentication

Authentication is automatically applied to the appropriate endpoints as defined in your OpenAPI spec. HTTP header authentication takes precedence over environment variables for the duration of each request.

When using HTTP mode, openapi-mcp serves an SSE (Server-Sent Events) based MCP server. For developers building HTTP clients, the package provides convenient URL helper functions:

import "github.com/jedisct1/openapi-mcp/pkg/openapi2mcp"

// Get the SSE connection URL
sseURL := openapi2mcp.GetSSEURL("http://localhost:8080")
// Returns: "http://localhost:8080/mcp/sse"

// Get the message endpoint URL (after receiving session ID from SSE)
messageURL := openapi2mcp.GetMessageURL("http://localhost:8080", sessionID)
// Returns: "http://localhost:8080/mcp/message?sessionId=<sessionID>"

Client Connection Flow:

1. Connect to the SSE endpoint to establish a persistent connection
2. Receive an endpoint event containing the session ID
3. Send JSON-RPC requests to the message endpoint using the session ID
4. Receive responses and notifications via the SSE stream

Example with curl:

# Step 1: Connect to SSE endpoint (keep connection open)
curl -N http://localhost:8080/mcp/sse

# Output: event: endpoint
#         data: /mcp/message?sessionId=<session-id>

# Step 2: Send JSON-RPC requests (in another terminal)
curl -X POST http://localhost:8080/mcp/message?sessionId=<session-id> \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You can easily integrate openapi-mcp with AI code editors that support MCP tools, such as Roo Code:

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

Add this configuration to your editor's MCP tools configuration to provide AI assistants with direct access to the API. The assistant can then discover and use the API operations without additional setup.

openapi-mcp includes powerful OpenAPI validation and linting capabilities to help you improve your API specifications:

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

# Comprehensive linting with detailed 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

The validate command performs essential checks:

• Missing operationId fields (required for MCP tool generation)
• Schema validation errors
• Basic structural issues

The lint command provides comprehensive analysis with suggestions for:

• Missing summaries and descriptions
• Untagged operations
• Parameter naming and type recommendations
• Security scheme validation
• Best practices for API design

Both commands exit with non-zero status codes when issues are found, making them perfect for CI/CD pipelines.

Both validate and lint commands can be run as HTTP services using the --http flag, allowing you to validate OpenAPI specs via REST API. Note that these endpoints are only available when using the validate or lint commands, not during normal MCP server operation:

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

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

API Endpoints:

• POST /validate - Validate OpenAPI specs for critical issues
• POST /lint - Comprehensive linting with detailed suggestions
• GET /health - Health check endpoint

Request Format:

{
  "openapi_spec": "openapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths: {}"
}

Response Format:

{
  "success": false,
  "error_count": 1,
  "warning_count": 2,
  "issues": [
    {
      "type": "error",
      "message": "Operation missing operationId",
      "suggestion": "Add an operationId field",
      "operation": "GET_/users",
      "path": "/users",
      "method": "GET"
    }
  ],
  "summary": "OpenAPI linting completed with issues: 1 errors, 2 warnings."
}

Example Usage:

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

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

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

bin/openapi-mcp --tag=admin examples/fastly-openapi-mcp.yaml

bin/openapi-mcp --include-desc-regex="user|account" examples/fastly-openapi-mcp.yaml
bin/openapi-mcp --exclude-desc-regex="deprecated" examples/fastly-openapi-mcp.yaml

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

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

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

openapi-mcp can be imported as a Go module in your projects:

package main

import (
        "github.com/jedisct1/openapi-mcp/pkg/openapi2mcp"
)

func main() {
        // Load OpenAPI spec
        doc, err := openapi2mcp.LoadOpenAPISpec("openapi.yaml")
        if err != nil {
                panic(err)
        }

        // Create MCP server
        srv := openapi2mcp.NewServer("myapi", doc.Info.Version, doc)

        // Serve over HTTP
        if err := openapi2mcp.ServeHTTP(srv, ":8080"); err != nil {
                panic(err)
        }

        // Or serve over stdio
        // if err := openapi2mcp.ServeStdio(srv); err != nil {
        //    panic(err)
        // }
}

See GoDoc for complete API documentation.

All tool results include 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"
    ]
  }
}

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.

Generate comprehensive documentation for all tools:

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

# HTML documentation
bin/openapi-mcp --doc=tools.html --doc-format=html examples/fastly-openapi-mcp.yaml

The documentation includes:

• Complete tool schemas with parameter types, constraints, and descriptions
• Example calls for each tool
• Response formats and examples
• Authentication requirements

Contributions are welcome! Please open an issue or pull request on GitHub.

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Run tests (go test ./...)
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request

This project is licensed under the MIT License.