home / mcp / openapi mcp server

Openapi MCP Server

Exposes OpenAPI 3.x specs as MCP tools with HTTP/stdio transports, validation, linting, and AI-friendly outputs.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jedisct1-openapi-mcp": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "API_KEY": "YOUR_API_KEY",
        "BASIC_AUTH": "user:pass",
        "BEARER_TOKEN": "YOUR_TOKEN",
        "OPENAPI_BASE_URL": "https://api.example.com"
      }
    }
  }
}

openapi-mcp turns any OpenAPI 3.x specification into a robust MCP tool server that is easy for AI agents and automation to consume. It supports both stdio and HTTP transports, validates and lints your OpenAPI spec, and serves generated MCP tools for each operation with consistent, machine-friendly output.

How to use

You run the MCP server with your OpenAPI spec, then connect with the MCP client to discover, inspect, and invoke the generated tools. You can operate over stdio for local use or run an HTTP server to expose MCP endpoints for remote clients. You can perform validation and linting through dedicated commands or HTTP services, and you can generate documentation, filter operations, and dry-run tool schemas for quick inspection.

Practical usage patterns include starting the MCP server in stdio mode to interact from a local client, or starting an HTTP server on a port to enable remote clients to connect. The client provides a readline-enabled interface with command history, so you can list tools, view tool schemas, and call tools with arguments. You can also request a full API description via a dedicated describe tool to help agents understand all available operations.

How to install

Prerequisites you need before building and running the MCP server:

- Go 1.21 or newer to build the binaries.

- An OpenAPI 3.x YAML or JSON specification file to convert into MCP tools.

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

# Build the binaries
make

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

Additional sections

Configuration and runtime options let you customize how the server behaves. You can enable HTTP transport, set a base URL for outbound requests, and supply authentication credentials through flags or environment variables. The tool also includes safety features that require confirmation for potentially dangerous actions like PUT, POST, or DELETE requests, and it can generate documentation in Markdown or HTML formats.

Key features include structured, machine-friendly output with explicit OutputFormat and OutputType fields, comprehensive OpenAPI validation and linting, AI-friendly tool schemas with rich parameter constraints and examples, and an interactive client with command history. The system is designed to minimize verbosity for AI agents while providing actionable error messages and helpful default values.

If you need to experiment with documentation, you can generate tool documentation in markdown or HTML. For debugging or CI workflows, you can perform a dry run to preview tool schemas as JSON without starting a full server.

Available tools

validate

Validate the OpenAPI spec and report critical issues such as missing operationIds or schema errors

lint

Lint the OpenAPI spec and provide best-practice suggestions for summaries, descriptions, tags, and parameter usage

describe

Describe tool that provides self-describing API documentation for all operations

tools_list

List available MCP tools exposed by the server (operations) via a dedicated endpoint or command

doc

Generate documentation for all tools in Markdown or HTML formats

filter

Filter operations by tag, description regex, or an explicit function list to narrow the set of exposed tools