Skip to content

README.md

Latest commit

 

History

History
227 lines (171 loc) · 5.63 KB

README.md

File metadata and controls

227 lines (171 loc) · 5.63 KB
Raw

@spec2tools/stdio-mcp

MCP (Model Context Protocol) server that exposes OpenAPI endpoints as tools via stdio transport. This allows AI agents like Claude to call any API described by an OpenAPI specification.

Installation

npm install @spec2tools/stdio-mcp
# or
pnpm add @spec2tools/stdio-mcp

Quick Start

With Claude Code

# Add as an MCP server
claude mcp add stdio my-api \
  -- npx @spec2tools/stdio-mcp ./path/to/openapi.yaml

# With authentication
claude mcp add --env API_KEY=your-api-key my-api \
  -- npx @spec2tools/stdio-mcp ./openapi.yaml

# With code mode (2 tools: search + execute)
claude mcp add my-api \
  -- npx @spec2tools/stdio-mcp ./openapi.yaml --code-mode

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@spec2tools/stdio-mcp", "./path/to/openapi.yaml"]
    }
  }
}

For authenticated APIs:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@spec2tools/stdio-mcp", "./openapi.yaml", "--api-key", "your-api-key"]
    }
  }
}

CLI Usage

# Start server with local spec
spec2tools-mcp ./openapi.yaml

# Start server with remote spec
spec2tools-mcp https://api.example.com/openapi.json

# Start with authentication
spec2tools-mcp ./api.yaml --api-key your-api-key

# Or use environment variable
API_KEY=your-api-key spec2tools-mcp ./api.yaml

Remote MCP Server

Proxy an existing remote MCP server through stdio. This lets you connect any HTTP or SSE-based MCP server to clients that only support stdio transport (like Claude Desktop), and optionally apply code mode to reduce token usage.

# Proxy via Streamable HTTP
spec2tools-mcp --http https://example.com/mcp

# Proxy via SSE
spec2tools-mcp --sse https://example.com/sse

# Proxy with code mode
spec2tools-mcp --sse https://example.com/sse --code-mode

With Claude Code:

claude mcp add my-remote-api \
  -- npx @spec2tools/stdio-mcp --sse https://example.com/sse --code-mode

Code Mode

Code mode collapses all API endpoints into 2 tools (search + execute), reducing token usage by ~99.9%. The model discovers endpoints via keyword search and calls them by writing Python code in a sandboxed interpreter.

spec2tools-mcp ./openapi.yaml --code-mode

Programmatic Usage

import { startMcpServer } from '@spec2tools/stdio-mcp';

await startMcpServer({
  spec: './openapi.yaml',
  name: 'my-api-server',
  version: '1.0.0',
  apiKey: 'your-api-key', // optional
});

CLI Options

Option Description
<spec-path> Path or URL to OpenAPI specification (JSON or YAML)
--name <name> Server name for MCP (default: openapi-mcp-server)
--version <ver> Server version for MCP (default: 1.0.0)
--api-key <key> API key or bearer token for authentication
--http <url> Connect to a remote MCP server (Streamable HTTP)
--sse <url> Connect to a remote MCP server (SSE transport)
--code-mode Use code mode (2 tools: search + execute)
-h, --help Show help message

Environment Variables

Variable Description
API_KEY API key or bearer token for authentication

How It Works

  1. Loads OpenAPI Spec: Reads your OpenAPI 3.x specification from a local file or URL (supports both JSON and YAML)

  2. Parses Operations: Converts each API operation into an MCP tool with:

    • Tool name from operationId (or generated from method + path)
    • Description from summary or description
    • Input schema from parameters and request body

  3. Starts MCP Server: Creates a stdio-based MCP server that AI agents can connect to

  4. Handles Tool Calls: When an agent calls a tool, the server:

    • Validates the parameters
    • Builds the HTTP request (URL, headers, body)
    • Adds authentication if configured
    • Executes the request and returns the response

Supported OpenAPI Features

  • HTTP Methods: GET, POST, PUT, PATCH, DELETE
  • Parameters: Path and query parameters (string, number, boolean, arrays)
  • Request Bodies: JSON with primitives and flat objects
  • Authentication: Bearer tokens, API keys (header or query)

Limitations

  • Nested objects beyond 1 level deep are not supported
  • Arrays of objects are not supported
  • Schema composition (anyOf, oneOf, allOf) is not supported
  • File uploads are not supported
  • $ref schema references are not supported

Example

Given this OpenAPI spec:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success

The MCP server will expose two tools:

  • listUsers(limit?: number) - List all users
  • getUser(id: number) - Get user by ID

An AI agent can then call these tools naturally:

"Get me the user with ID 42"

The agent will call getUser({ id: 42 }) and receive the API response.

Related Packages

License

MIT