Openapi To Mcp Converter

Pricing

Rating

Developer

Actor stats

Categories

Share

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 =newApifyClient({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.