mcpgen: Seamlessly Transform OpenAPI APIs into AI Agent Tools

mcpgen is a command-line tool that seamlessly generates production-ready Model Context Protocol (MCP) server boilerplate from your OpenAPI specifications, enabling you to easily expose your existing APIs as powerful tools for AI agents.

Key Features

• OpenAPI Compatibility: Reads and processes OpenAPI specifications in YAML or JSON format, supporting versions 3.0.
• Comprehensive MCP Server Generation: Generates the full Go boilerplate required to set up an MCP server, including server initialization, tool registration, and handler skeletons.
• Accurate Schema Translation: Automatically translates OpenAPI schema definitions into the necessary JSON Schemas for tool inputs (compatible with MCP) and generates detailed markdown-based Response Templates (Prompts) for various status codes and content types, providing rich context for AI models.
• Advanced Schema Support: Handles complex OpenAPI schema constructs, including:
  • Arrays and nested structures
  • Type unions and oneOf/anyOf/allOf combinators
  • Recursive type definitions
  • Validation constraints (e.g., minimum, maximum, maxLength, pattern)
• Multiple Content Type Handling: Correctly processes and generates templates for operations defining multiple request and response content types.
• Generated Code Quality: Produces well-structured, idiomatic Go code with embedded schemas and prompts, leveraging constants for clarity and maintainability.
• Optional Client & Types Generation: Can optionally generate a Go HTTP client and corresponding Go types based on your OpenAPI schema, simplifying the implementation logic within the generated MCP handlers.
• Developer Friendly: Provides clear handler function skeletons with guidance on where to integrate your core logic to connect to the actual backend API.
• Battle-Tested Foundation: The code generation logic is backed by extensive testing, ensuring high reliability (as demonstrated by 94% coverage and 200% test volume).

Installation

go install github.com/lyeslabs/mcpgen/cmd/mcpgen@latest

By default, the binary is installed to $HOME/go/bin (or %USERPROFILE%\go\bin on Windows). Make sure this directory is in your PATH.

Usage

mcpgen --input openapi.yaml --output generated-server

Required flags

• --input Path to your OpenAPI specification file (YAML or JSON).

• --output Output directory for the generated MCP server boilerplate.

Optional flags

• --validation Enable OpenAPI validation (default: false).

• --package Name for the generated Go package (default: mcpgen).

• --includes Comma-separated list of additional includes for the generated code. Use httpclient,types to generate the HTTP client and types.

Example

mcpgen --input api/openapi.yaml --output ./generated-server --validation --package myserver --includes=httpclient,types

How It Works

mcpgen acts as a bridge between your declarative OpenAPI specification and the programmatic Go code required for an MCP server. It reads your OpenAPI definition and automatically generates the necessary boilerplate, including the structured schemas and prompts essential for effective AI agent interaction.

Let's illustrate this with an example of a moderately complex endpoint defined in OpenAPI:

# This is a snippet from your OpenAPI specification
/todos:
    get:
      tags:
        - Todos
      summary: List all todo items
      description: Retrieves a list of todo items, optionally filtered by status.
      operationId: listTodos
      parameters:
        - name: status
          in: query
          description: Filter todos by status (e.g., "pending", "completed")
          required: false
          schema:
            type: string
            enum: [pending, completed, in-progress]
        - n

... [View full README on GitHub](https://github.com/lyeslabs/mcpgen#readme)