What is Openai To Mcp

openai-to-mcp is a Model Context Protocol (MCP) server that converts any OpenAPI/Swagger specification into an MCP server, enabling Large Language Models (LLMs) to interact with REST APIs through a standardized interface.

Use cases

Use cases for openai-to-mcp include automating API interactions for chatbots, enhancing data retrieval processes in applications, and simplifying the integration of LLMs with existing RESTful services.

How to use

To use openai-to-mcp, add it to your MCP client’s configuration file by specifying the command and environment variables for your OpenAPI specification URL and base URL. Supported clients include Claude Desktop, Cursor, Windsurf, and VS Code.

Key features

Key features of openai-to-mcp include automatic conversion of API specifications into MCP-compatible tools, type-safe interactions with REST APIs, and the elimination of manual tool creation and maintenance.

Where to use

openai-to-mcp can be used in various fields such as software development, API integration, and machine learning, where interactions between LLMs and REST APIs are required.

OpenAPI to MCP Server

A Model Context Protocol (MCP) server that converts any OpenAPI/Swagger specification into an MCP server, allowing Large Language Models (LLMs) to interact with REST APIs through a standardized interface.

Why Use OpenAPI to MCP?

The OpenAPI to MCP server bridges the gap between REST APIs and LLM agents by:

• Automatically converting API specifications into MCP-compatible tools
• Providing type-safe interactions with any REST API
• Eliminating the need for manual tool creation and maintenance

Client Configuration

Add the OpenAPI to MCP server to your MCP client’s configuration file:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-to-mcp"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "path/to/your/swagger.yml",
        "OPENAPI_SPEC_BASE_URL": "http://api.example.com"
      }
    }
  }
}

Configuration file locations for supported clients:

• Claude Desktop

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

• Cursor: ~/.cursor/mcp.json

• Windsurf: ~/.codeium/windsurf/mcp_config.json

• VS Code:

  • Workspace configuration: .vscode/mcp.json
  • Command line:

    code --add-mcp "{\"name\":\"openapi-mcp\",\"command\":\"npx\",\"args\":[\"-y\",\"openapi-to-mcp\"],\"env\":{\"OPENAPI_SPEC_URL\":\"path/to/your/swagger.yml\",\"OPENAPI_SPEC_BASE_URL\":\"http://api.example.com\"}}"
    

  Example .vscode/mcp.json:

  {
    "servers": {
      "openapi-mcp": {
        "type": "stdio",
        "command": "npx",
        "args": [
          "-y",
          "openapi-to-mcp"
        ],
        "env": {
          "OPENAPI_SPEC_URL": "path/to/your/swagger.yml",
          "OPENAPI_SPEC_BASE_URL": "http://api.example.com"
        }
      }
    }
  }
  

Example Usage

Here’s an example of how the server converts OpenAPI operations into MCP tools:

OpenAPI Specification

paths:
  /pets:
    get:
      operationId: getPets
      summary: List all pets
      parameters:
        - name: limit
          in: query
          type: integer

Generated MCP Tool

{
  name: "getPets",
  description: "List all pets",
  parameters: {
    limit: z.number().int().optional()
  }
}

Features in Detail

1. API Specification Support

• OpenAPI 2.0 (Swagger)
• OpenAPI 3.0
• Local file paths
• Remote HTTP URLs
• YAML and JSON formats

2. Authentication

The server supports various authentication methods:

API Key Authentication

{
  "env": {
    "OPENAPI_SPEC_HEADERS": "{\"X-API-Key\": \"your-api-key\"}"
  }
}

Bearer Token

{
  "env": {
    "OPENAPI_SPEC_HEADERS": "{\"Authorization\": \"Bearer your-token\"}"
  }
}

Certificate-Based Authentication

{
  "env": {
    "OPENAPI_CERT_PATH": "/path/to/client.crt",
    "OPENAPI_KEY_PATH": "/path/to/client.key",
    "OPENAPI_CERT_PASSPHRASE": "optional-passphrase"
  }
}

OAuth2 Authentication

{
  "env": {
    "OPENAPI_OAUTH_CLIENT_ID": "your-client-id",
    "OPENAPI_OAUTH_CLIENT_SECRET": "your-client-secret",
    "OPENAPI_OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token",
    "OPENAPI_OAUTH_SCOPES": "read:data,write:data"
  }
}

3. Request/Response Handling

• Automatic parameter validation
• JSON Schema to Zod conversion
• Content type negotiation
• File uploads
• Binary responses
• Error mapping

4. Type Safety

• Full TypeScript support
• Automatic type generation
• Runtime type validation
• Type-safe API calls

Command Line Flags

• --spec <path>: Path to OpenAPI specification file
• --base-url <url>: Base URL for API requests
• --headers <json>: Additional headers as JSON string
• --verbose: Enable detailed logging
• --log-level <level>: Set log level (error, warn, info, debug)
• --cert-path <path>: Path to client certificate file
• --key-path <path>: Path to client key file
• --cert-passphrase <string>: Passphrase for certificate
• --oauth-client-id <id>: OAuth client ID
• --oauth-client-secret <secret>: OAuth client secret
• --oauth-token-url <url>: OAuth token endpoint URL
• --oauth-scopes <scopes>: Comma-separated list of OAuth scopes
• --version: Display version information
• --help: Show help information

Docker Support

Building the Docker Image

To build the Docker image:

# Clone the repository
git clone https://github.com/your-username/openapi-to-mcp
cd openapi-to-mcp

# Build the Docker image
docker build -t openapi-to-mcp .

Running the Container

You can run the server using Docker:

docker run \
  -e OPENAPI_SPEC_URL="https://petstore.swagger.io/v2/swagger.json" \
  -e OPENAPI_SPEC_BASE_URL="https://petstore.swagger.io/v2" \
  openapi-to-mcp

Environment Variables

The server uses the following environment variables:

Variable	Description	Requirement	Notes
OPENAPI_SPEC_URL	Path or URL to OpenAPI spec	Required	Local file path or HTTP(S) URL
OPENAPI_SPEC_BASE_URL	Base URL for API requests	Required	API server base URL
OPENAPI_SPEC_HEADERS	Additional headers as JSON	Optional	Used for API key and token auth
OPENAPI_CERT_PATH	Path to client certificate	Optional*	Required for certificate auth
OPENAPI_KEY_PATH	Path to client key	Optional*	Required for certificate auth
OPENAPI_CERT_PASSPHRASE	Passphrase for client key	Optional	Only needed if key is encrypted
OPENAPI_OAUTH_CLIENT_ID	OAuth client ID	Optional*	Required for OAuth2 auth
OPENAPI_OAUTH_CLIENT_SECRET	OAuth client secret	Optional*	Required for OAuth2 auth
OPENAPI_OAUTH_TOKEN_URL	OAuth token URL	Optional*	Required for OAuth2 auth
OPENAPI_OAUTH_SCOPES	OAuth scopes (comma-separated)	Optional	Used for OAuth2 scope requests
NODE_EXTRA_CA_CERTS	Custom CA certificates path	Optional	For self-signed certificates
NODE_TLS_REJECT_UNAUTHORIZED	Disable TLS validation (0 or 1)	Optional	Use with caution for testing
LOG_LEVEL	Log level (error, warn, info, debug)	Optional	Defaults to “info”

*These variables are conditionally required depending on the authentication method you’re using.

Troubleshooting

Enable Debug Logs

npx openapi-to-mcp --debug

Common Issues

3. Version Conflicts
   • Ensure Node.js version ≥ 18
   • Check package.json for compatibility

Logs Location

• MacOS / Linux:

  tail -f ~/.openapi-mcp/logs/server.log
  

• Windows:

  Get-Content "$env:USERPROFILE\.openapi-mcp\logs\server.log" -Wait
  

1. Spec Parser: Loads and validates the OpenAPI specification
2. Operation Generator: Converts API operations to MCP tools
3. MCP Tools: Exposes operations as standardized tools
4. API Calls: Makes actual HTTP requests to the API

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Development Setup

git clone https://github.com/your-username/openapi-to-mcp
cd openapi-to-mcp
npm install
npm run build
npm run start

Testing

Run the test suite:

npm test

Start the test server:

npm run start:server

License

MIT License - see LICENSE file for details

Support

• Open an issue