openapi-mcp

openapi-mcp

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 (Machine-to-Computer 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.

📋 Table of Contents

• 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
    • 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
  • 📚 Library Usage
  • 📊 Output Structure
  • 🛡️ Safety Features
  • 📝 Documentation Generation
  • 🙌 Contributing
  • 📄 License

✨ Features

• 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: All tool calls are validated against OpenAPI schemas before execution
• Safety Features: Confirmation required for dangerous operations (PUT/POST/DELETE)
• Documentation: Built-in documentation generation in Markdown or HTML
• Agent-Friendly: Designed specifically for AI agents with structured errors, hints, and examples
• 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

🤖 AI Agent Integration

openapi-mcp is designed for seamless integration with AI coding agents, LLMs, and automation tools:

• Structured JSON Responses: Every response includes OutputFormat and OutputType fields
• Rich Schema Information: All tools provide detailed parameter constraints and examples
• Actionable Error Messages: Validation errors include detailed information and suggestions
• Safety Confirmations: Standardized confirmation workflow for dangerous operations
• Self-Describing API: The describe tool provides complete documentation for all operations
• Minimal Verbosity: No redundant warnings or messages to confuse agents

🔧 Installation

Prerequisites

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

Build 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

1. Run 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

2. Use 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 all standard OpenAPI authentication methods:

# 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

Authentication is automatically applied to the appropriate endpoints as defined in your OpenAPI spec.

🛠️ Usage Examples

Integration with AI Code Editors

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.

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 by Tag

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

Include/Exclude Operations by Description

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

Print Summary

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

Post-Process Schema with External Command

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

📚 Library Usage

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

package main

import (
	"github.com/getkin/kin-openapi/openapi3"
	"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.

📊 Output Structure

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"
    ]
  }
}

🛡️ 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.

📝 Documentation Generation

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

🙌 Contributing

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

📄 License

This project is licensed under the MIT License.