openapi-mcp Documentation

Welcome to the official documentation for openapi-mcp, a tool that transforms any OpenAPI 3.x specification into a powerful, AI-friendly MCP (Model Context Protocol) tool server.

What is openapi-mcp?

openapi-mcp is a tool that loads and validates OpenAPI specifications (YAML or JSON), generates MCP tools for each operation, and starts an MCP stdio or HTTP server. This enables AI agents and automation to interact with any API defined by an OpenAPI spec.

In essence, it bridges the gap between API definitions and AI tools, making any API accessible to AI agents, LLMs, and automation tools with consistent, structured output.

Key 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 (StreamableHTTP is default for HTTP, SSE also available)
  • 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 to make any OpenAPI-documented API accessible to AI coding agents, editors, and LLM-based tools (such as Cursor, Copilot, GPT-4, and others). By exposing each API operation as a machine-readable tool with rich schemas, examples, and structured output, agents can:

  • Discover available operations and their arguments
  • Validate and construct correct API calls
  • Handle errors, confirmations, and streaming output
  • Chain multiple API calls together in workflows

Quick Example

Run an MCP server for an OpenAPI spec:

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

Use the interactive client to explore the API:

bin/mcp-client bin/openapi-mcp examples/fastly-openapi-mcp.yaml

Client session:

mcp> list
["listServices", "createService", "getService", "updateService", "deleteService", ...]

mcp> schema createService
Schema for createService:
{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "The name of the service."},
    "comment": {"type": "string", "description": "A freeform descriptive note."},
    "type": {"type": "string", "enum": ["vcl", "wasm"], "description": "The type of this service."}
  },
  "required": ["name", "type"]
}
Example: call createService {"name": "My Service", "type": "vcl"}

mcp> call createService {"name": "My Service", "type": "vcl"}
HTTP POST /service
Status: 200
Response:
{
  "id": "SU1Z0isxPaozGVKXdv0eY",
  "name": "My Service",
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "type": "vcl",
  "created_at": "2016-08-17T19:27:28+00:00",
  "updated_at": "2016-08-17T19:27:28+00:00"
}

Next Steps

To get started with openapi-mcp, check out the following sections: