kumoctl by kumolabai - MCP Server

kumoctl

A CLI tool to dynamically serve MCP (Model Context Protocol) servers from OpenAPI specifications. Each operation/path in your OpenAPI spec becomes an MCP tool that can be called by LLM clients like Claude.

Installation

Linux, macOS

curl -fsSL https://get.kumolab.ai | sh

Windows

irm https://get.kumolab.ai/install.ps1 | iex

Usage

Quick Start with Auto-Configuration

The fastest way to get started is using the configure command to automatically set up kumoctl with your LLM client:

# Auto-configure for Claude Desktop
kumoctl configure examples/openapi2-example.json my-api-server

# Preview configuration without installing
kumoctl configure --dry-run examples/openapi3-example.yaml weather-api

# Configure for cursor
kumoctl configure --client=cursor examples/openapi2-example.json my-tools

Manual Usage

# Serve MCP from an OpenAPI spec file or URL
kumoctl serve <path-or-url-to-openapi-spec>

# Examples
kumoctl serve ./examples/openapi2-example.json
kumoctl serve ./examples/openapi3-example.yaml

Command Line Options

# Get help for all commands
kumoctl --help

# Get help for specific commands
kumoctl serve --help
kumoctl configure --help

Commands

`kumoctl serve`

Starts an MCP server that exposes tools based on your OpenAPI specification.

kumoctl serve <path-to-openapi-spec>

`kumoctl configure`

Automatically configures kumoctl as an MCP server in your LLM client. This eliminates the need for manual JSON configuration.

kumoctl configure [OPTIONS] <spec-file-or-url> <server-name>

Options:

--dry-run: Preview the configuration without installing it
--client <client>: Target LLM client (claude-desktop, cursor, custom)
--config-path <path>: Custom path to configuration file

Supported Clients:

Claude Desktop (default): Automatically adds kumoctl to your Claude Desktop MCP configuration
Cursor: Automatically adds kumoctl to Cursor. MCP support in Cursor IDE is Experimental

Examples:

# Configure for Claude Desktop (easiest method)
kumoctl configure examples/openapi2-example.json my-api

# Preview what would be configured
kumoctl configure --dry-run examples/openapi3-example.yaml weather-service

# Get JSON for manual configuration
kumoctl configure --client=custom examples/openapi2-example.json my-tools

What it does:

Locates your LLM client's configuration file
Adds kumoctl with your OpenAPI spec to the MCP servers list
Uses absolute paths to ensure reliability
Preserves existing MCP server configurations
Provides clear next steps (like restarting Claude Desktop)

How It Works

Load OpenAPI Spec: kumoctl reads your OpenAPI 2.0 or 3.0 specification
Generate MCP Tools: Each operation (GET, POST, etc.) becomes an MCP tool
Create Input Schemas: Tool schemas include all parameters (path, query, body)
Handle API Calls: When a tool is called, kumoctl makes HTTP requests to your API
Return Responses: API responses are returned to the MCP client

Tool Naming

Tools are named using the following priority:

operationId (if specified in the spec)
{method}_{path} (cleaned and normalized)

Input Schema Generation

For each operation, kumoctl creates a JSON schema that includes:

Path Parameters: Required parameters in the URL path
Query Parameters: Optional/required query string parameters
Header Parameters: HTTP headers to be sent
Body Parameters: Individual fields from request body schemas (properly expanded from $ref)

Example: OpenAPI 2.0 Body Parameter Expansion

OpenAPI Spec:

{
  "paths": {
    "/users": {
      "post": {
        "operationId": "users_create",
        "parameters": [
          {
            "name": "data",
            "in": "body",
            "schema": {"$ref": "#/definitions/UserRequest"}
          }
        ]
      }
    }
  },
  "definitions": {
    "UserRequest": {
      "type": "object",
      "required": ["name", "email"],
      "properties": {
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer"}
      }
    }
  }
}

Generated MCP Tool Schema:

{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string", "format": "email"},
    "age": {"type": "integer"}
  }
}

Limitations and Considerations

LLM Context Limits

⚠️ Large OpenAPI Specifications: If your OpenAPI spec is very large (hundreds of operations), the generated MCP tools may exceed LLM context limits.

Current Limitations

Authentication: Currently no built-in authentication support
Response Schemas: Tool outputs are raw HTTP responses
Error Handling: HTTP errors are returned as-is
Base URL Resolution: Uses the first server URL found in the spec
- OpenAPI 2.0: Constructs from host, basePath, and schemes
- OpenAPI 3.0: Uses first entry in servers array
STDIO Transport ONLY: kumoctl only support STDIO transport for now

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request