Openapi To Mcp Converter

Convert any OpenAPI specification into a Model Context Protocol (MCP) server that AI assistants can use to interact with REST APIs.

Features

• Universal OpenAPI Support: Works with OpenAPI v3.0 and v3.1 specifications
• Flexible Input: Accept OpenAPI specs from URLs or raw JSON/YAML strings
• Smart Filtering: Include/exclude endpoints using regex patterns
• Authentication Support: Bearer tokens, API keys, and basic auth
• Multiple Output Formats: Generate MCP server packages, JSON manifests, or both
• Production Ready: Includes error handling, validation, and structured logging

How It Works

1. Input: Provide an OpenAPI specification URL or raw spec
2. Parse: Extract endpoints, parameters, request/response schemas
3. Transform: Convert each endpoint into an MCP tool with proper schemas
4. Generate: Create a ready-to-use MCP server package or JSON manifest
5. Deploy: Use the generated MCP server with any AI assistant

Input Parameters

Required

• openapiSource (string): URL or raw JSON/YAML of the OpenAPI specification

Optional

• serverName (string): Unique identifier for the MCP server (default: openapi-mcp-server)
• serverDescription (string): Human-readable description
• includeEndpoints (array): Regex patterns to include specific endpoints
• excludeEndpoints (array): Regex patterns to exclude endpoints
• authentication (object): Auth configuration
  • type: none, bearer, apiKey, or basic
  • token: Bearer token or API key value
  • apiKeyHeader: Header name for API key (e.g., X-API-Key)
  • username: For basic auth
  • password: For basic auth
• baseUrl (string): Override the base URL from the spec
• outputFormat (string): mcp-package, json-manifest, or both (default: both)
• includeExamples (boolean): Include examples in tool descriptions (default: true)
• maxEndpoints (integer): Maximum endpoints to process (default: 100, max: 500)

Output

Dataset

Each run produces a dataset with:

1. Summary record: Overview of processed endpoints
2. Endpoint records: Detailed info for each API endpoint including MCP tool name

Key-Value Store

• manifest.json: Complete MCP manifest with all tools and metadata
• mcp-server.zip: Ready-to-deploy MCP server package (includes package.json, index.js, README.md)

Usage Examples

Basic Usage

{
    "openapiSource": "https://petstore3.swagger.io/api/v3/openapi.json",
    "serverName": "petstore-mcp",
    "serverDescription": "MCP server for Petstore API"
}

With Authentication

{
    "openapiSource": "https://api.example.com/openapi.json",
    "serverName": "example-api-mcp",
    "authentication": {
        "type": "bearer",
        "token": "your-api-token-here"
    }
}

With Endpoint Filtering

{
    "openapiSource": "https://api.example.com/openapi.json",
    "includeEndpoints": ["GET /users.*", "POST /users"],
    "excludeEndpoints": ["DELETE .*"]
}

From Raw YAML

{
    "openapiSource": "openapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths:\n  /hello:\n    get:\n      summary: Say hello\n      responses:\n        '200':\n          description: Success"
}

Deploying the MCP Server

After the actor completes:

1. Download mcp-server.zip from the key-value store
2. Extract the archive
3. Install dependencies: npm install
4. Run the server: node index.js
5. Connect it to your AI assistant (Claude Desktop, etc.)

Example MCP Configuration (Claude Desktop)

{
    "mcpServers": {
        "petstore-mcp": {
            "command": "node",
            "args": ["/path/to/extracted/mcp-server/index.js"]
        }
    }
}

API Integration

Use the Apify API to automate OpenAPI to MCP conversion:

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const run = await client.actor('YOUR_USERNAME/openapi-to-mcp-converter').call({
    openapiSource: 'https://api.example.com/openapi.json',
    serverName: 'my-api-mcp',
    authentication: {
        type: 'bearer',
        token: process.env.API_TOKEN,
    },
});

const { defaultKeyValueStoreId } = run;
const kvStore = client.keyValueStore(defaultKeyValueStoreId);

// Download the MCP server package
const mcpPackage = await kvStore.getValue('mcp-server.zip');

Use Cases

• API Integration: Make any REST API accessible to AI assistants
• Legacy API Modernization: Bridge old APIs with modern AI tooling
• Rapid Prototyping: Quickly test AI interactions with APIs
• Multi-API Orchestration: Create multiple MCP servers for different services
• Developer Tools: Generate MCP servers for internal APIs

Limitations

• Only supports OpenAPI v3.0 and v3.1
• Complex authentication flows (OAuth2, etc.) require manual customization
• Generated MCP server code is a starting point and may need refinement for production
• Maximum 500 endpoints per run

Technical Details

• Runtime: Node.js 18+
• Dependencies: apify, openapi-types, yaml, zod, archiver, fs-extra
• Output: MCP SDK v1.0+ compatible servers

Troubleshooting

"Failed to fetch OpenAPI spec"

• Verify the URL is accessible
• Check if authentication is required for the spec endpoint
• Ensure the URL returns valid JSON or YAML

"No endpoints found"

• Check your include/exclude patterns
• Verify the OpenAPI spec has valid paths
• Increase maxEndpoints if needed

"Invalid OpenAPI specification"

• Ensure the spec is valid OpenAPI v3.0 or v3.1
• Use an OpenAPI validator to check the spec first
• Try converting v2.0 (Swagger) specs to v3.0 first

Support

For issues, feature requests, or questions, please open an issue on the actor's repository.