Mcp Openapi Server

OpenAPI MCP Server

[](https://smithery.ai/server/@ivo-toby/mcp-openapi-server)

A Model Context Protocol (MCP) server that exposes OpenAPI endpoints as MCP tools, along with optional support for MCP prompts and resources. This server allows Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the MCP protocol.

📖 Documentation

• [User Guide](#user-guide) - For users wanting to use this MCP server with Claude Desktop, Cursor, or other MCP clients
• [Library Usage](#library-usage) - For developers creating custom MCP servers using this package as a library
• [Developer Guide](./docs/developer-guide.md) - For contributors and developers working on the codebase
• [AuthProvider Guide](./docs/auth-provider-guide.md) - Detailed authentication patterns and examples

---

User Guide

This section covers how to use the MCP server as an end user with Claude Desktop, Cursor, or other MCP-compatible tools.

Overview

This MCP server can be used in two ways:

1. CLI Tool: Use npx @ivotoby/openapi-mcp-server directly with command-line arguments for quick setup
2. Library: Import and use the OpenAPIServer class in your own Node.js applications for custom implementations

The server supports two transport methods:

1. Stdio Transport (default): For direct integration with AI systems like Claude Desktop that manage MCP connections through standard input/output.
2. Streamable HTTP Transport: For connecting to the server over HTTP, allowing web clients and other HTTP-capable systems to use the MCP protocol.

Quick Start for Users

Option 1: Using with Claude Desktop (Stdio Transport)

No need to clone this repository. Simply configure Claude Desktop to use this MCP server:

1. Locate or create your Claude Desktop configuration file:

• On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

1. Add the following configuration:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

1. Replace the environment variables with your actual API configuration:

• API_BASE_URL: The base URL of your API
• OPENAPI_SPEC_PATH: URL or path to your OpenAPI specification
• API_HEADERS: Comma-separated key:value pairs for API authentication headers

Option 2: Using with HTTP Clients (HTTP Transport)

To use the server with HTTP clients:

1. No installation required! Use npx to run the package directly:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000

1. Interact with the server using HTTP requests:

# Initialize a session (first request)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'

# The response includes a Mcp-Session-Id header that you must use for subsequent requests
# and the InitializeResult directly in the POST response body.

# Send a request to list tools
# This also receives its response directly on this POST request.
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Open a streaming connection for other server responses (e.g., tool execution results)
# This uses Server-Sent Events (SSE).
curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

# Example: Execute a tool (response will arrive on the GET stream)
# curl -X POST http://localhost:3000/mcp \
#  -H "Content-Type: application/json" \
#  -H "Mcp-Session-Id: your-session-id" \
#  -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'

# Terminate the session when done
curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

Configuration Options

The server can be configured through environment variables or command line arguments:

Environment Variables

• API_BASE_URL - Base URL for the API endpoints
• OPENAPI_SPEC_PATH - Path or URL to OpenAPI specification
• OPENAPI_SPEC_FROM_STDIN - Set to "true" to read OpenAPI spec from standard input
• OPENAPI_SPEC_INLINE - Provide OpenAPI spec content directly as a string
• API_HEADERS - Comma-separated key:value pairs for API headers
• CLIENT_CERT_PATH - Path to client certificate PEM file for mutual TLS
• CLIENT_KEY_PATH - Path to client private key PEM file for mutual TLS
• CA_CERT_PATH - Path to custom CA certificate PEM file for private/internal CAs
• CLIENT_KEY_PASSPHRASE - Passphrase for an encrypted client private key
• REJECT_UNAUTHORIZED - Whether to reject untrusted server certificates (default: true)
• SERVER_NAME - Name for the MCP server (default: "mcp-openapi-server")
• SERVER_VERSION - Version of the server (default: "1.0.0")
• TRANSPORT_TYPE - Transport type to use: "stdio" or "http" (default: "stdio")
• HTTP_PORT - Port for HTTP transport (default: 3000)
• HTTP_HOST - Host for HTTP transport (default: "127.0.0.1")
• ENDPOINT_PATH - Endpoint path for HTTP transport (default: "/mcp")
• TOOLS_MODE - Tools loading mode: "all" (load all endpoint-based tools), "dynamic" (load only meta-tools), or "explicit" (load only tools specified in includeTools) (default: "all")
• DISABLE_ABBREVIATION - Disable name optimization (this could throw errors when name is > 64 chars)
• VERBOSE - Enable operational logging (true by default; set to false to suppress non-essential logs)
• PROMPTS_PATH - Path or URL to prompts JSON/YAML file
• PROMPTS_INLINE - Provide prompts directly as JSON string
• RESOURCES_PATH - Path or URL to resources JSON/YAML file
• RESOURCES_INLINE - Provide resources directly as JSON string

Command Line Arguments

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --exclude-tag admin \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --name "my-mcp-server" \
  --server-version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp \
  --disable-abbreviation true \
  --verbose false

Mutual TLS (mTLS)

If your upstream API requires client certificate authentication, you can attach TLS credentials directly to outbound requests.

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://secure-api.example.com \
  --openapi-spec https://secure-api.example.com/openapi.json \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --headers "Authorization:Bearer token123"

This is orthogonal to HTTP-level auth, so mTLS can be combined with static headers or an AuthProvider.

TLS-related options only apply when --api-base-url uses https://.

For private CAs or encrypted keys:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://internal-api.example.com \
  --openapi-spec ./openapi.yaml \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --client-key-passphrase "$CLIENT_KEY_PASSPHRASE" \
  --ca-cert ./certs/internal-ca.pem \
  --reject-unauthorized false

• --client-cert / CLIENT_CERT_PATH: client certificate PEM file
• --client-key / CLIENT_KEY_PATH: client private key PEM file
• --client-key-passphrase / CLIENT_KEY_PASSPHRASE: passphrase for encrypted private keys
• --ca-cert / CA_CERT_PATH: custom CA bundle for private/internal certificate authorities
• --reject-unauthorized / REJECT_UNAUTHORIZED: set to false only when you intentionally want to allow self-signed or otherwise untrusted server certificates

Set --verbose false or VERBOSE=false if you want the server to stay quiet in scripts or embedded environments.

OpenAPI Specification Loading

The MCP server supports multiple methods for loading OpenAPI specifications, providing flexibility for different deployment scenarios:

1. URL Loading (Default)

Load the OpenAPI spec from a remote URL:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json

2. Local File Loading

Load the OpenAPI spec from a local file:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./path/to/openapi.yaml

3. Standard Input Loading

Read the OpenAPI spec from standard input (useful for piping or containerized environments):

# Pipe from file
cat openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# Pipe from curl
curl -s https://api.example.com/openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# Using environment variable
export OPENAPI_SPEC_FROM_STDIN=true
echo '{"openapi": "3.0.0", ...}' | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com

4. Inline Specification

Provide the OpenAPI spec content directly as a command line argument:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-inline '{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0.0"}, "paths": {}}'

# Using environment variable
export OPENAPI_SPEC_INLINE='{"openapi": "3.0.0", ...}'
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com

Supported Formats

All loading methods support both JSON and YAML formats. The server automatically detects the format and parses accordingly.

Docker and Container Usage

For containerized deployments, you can mount OpenAPI specs or use stdin:

# Mount local file
docker run -v /path/to/spec:/app/spec.json your-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec /app/spec.json

# Use stdin with docker
cat openapi.json | docker run -i your-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

Error Handling

The server provides detailed error messages for spec loading failures:

• URL loading: HTTP status codes and network errors
• File loading: File system errors (not found, permissions, etc.)
• Stdin loading: Empty input or read errors
• Inline loading: Missing content errors
• Parsing errors: Detailed JSON/YAML syntax error messages

Validation

Only one specification source can be used at a time. The server will validate that exactly one of the following is provided:

• --openapi-spec (URL or file path)
• --spec-from-stdin
• --spec-inline

If multiple sources are specified, the server will exit with an error message.

Tool Loading & Filtering Options

Based on the Stainless article "What We Learned Converting Complex OpenAPI Specs to MCP Servers" (https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers), the following flags were added to control which API endpoints (tools) are loaded:

• --tools : Choose tool loading mode:
• all (default): Load all tools from the OpenAPI spec, applying any specified filters
• dynamic: Load only dynamic meta-tools (list-api-endpoints, get-api-endpoint-schema, invoke-api-endpoint). --exclude-tag still applies to dynamic endpoint discovery and invocation.
• explicit: Load only tools explicitly listed in --tool options, ignoring include filters. --exclude-tag still applies as a deny filter.
• --tool : Import only specified tool IDs or names. Can be used multiple times. In all mode, this bypasses --tag, --resource, and --operation, but not --exclude-tag.
• --tag : Import only tools with the specified OpenAPI tag. Can be used multiple times.
• --exclude-tag : Exclude tools with the specified OpenAPI tag. Can be used multiple times. Excluded tags take precedence over --tool.
• --resource : Import only tools under the specified resource path prefixes. Can be used multiple times.
• --operation : Import only tools for the specified HTTP methods (get, post, etc). Can be used multiple times.

Tag filters are tool-surface controls, not authorization. Keep protecting sensitive endpoints with the upstream API's auth model. Untagged endpoints are not affected by --exclude-tag.

Examples:

# Load only dynamic meta-tools
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic

# Load only explicitly specified tools (ignores other filters)
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools explicit --tool GET::users --tool POST::users

# Load only the GET /users endpoint tool (using all mode with filtering)
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users

# Load tools tagged with "user" under the "/users" resource
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tag user --resource users

# Exclude admin and internal endpoints from any tool loading mode
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --exclude-tag admin --exclude-tag internal

# Load only POST operations
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --operation post

Prompts and Resources

In addition to exposing OpenAPI endpoints as tools, this server can expose prompts (reusable templates) and resources (static content) via the MCP protocol.

What Are Prompts and Resources?

| Feature | Purpose | Use Case | | ------------- | --------------------------------------------- | --------------------------- | | Tools | API endpoints for the AI to execute | Making API calls | | Prompts | Templated messages with argument substitution | Reusable workflow templates | | Resources | Read-only content for context | API documentation, schemas |

Loading Prompts

Prompts can be loaded from files, URLs, or inline JSON:

# Load from local file
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts ./prompts.json

# Load from URL
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts https://example.com/mcp/prompts.json

# Inline JSON
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts-inline '[{"name":"greet","title":"Greeting","template":"Hello {{name}}!"}]'

Prompts File Format (JSON):

[
  {
    "name": "api_request",
    "title": "API Request Helper",
    "description": "Helps generate API request templates",
    "arguments": [
      { "name": "endpoint", "description": "API endpoint path", "required": true },
      { "name": "method", "description": "HTTP method", "required": false }
    ],
    "template": "Create a {{method}} request to {{endpoint}} with proper para

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ivo-toby](https://github.com/ivo-toby)
- **Source:** [ivo-toby/mcp-openapi-server](https://github.com/ivo-toby/mcp-openapi-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.