MCPify
A dynamic proxy that converts OpenAPI Specification (OAS) endpoints into Message Communication Protocol (MCP) tools on the fly.
Overview
MCPify enables seamless integration between REST APIs and AI agents by dynamically translating OpenAPI endpoints into MCP tools. Unlike static code generators, MCPify creates a live proxy server that:
- Parses OpenAPI specs from local files or URLs
- Dynamically maps REST endpoints to MCP tools with appropriate schemas
- Proxies requests between the MCP client and the underlying REST API
- Handles conversions between MCP and REST formats in real-time
This allows AI agents to use existing REST APIs as if they were native MCP tools without any manual implementation required.
Features
Status | Feature |
---|---|
Usage
# Start a proxy server using a local OpenAPI specification
npx mcpify --spec api-spec.yaml --base-url https://api.example.com
# Start a proxy server using a remote OpenAPI specification
npx mcpify --spec https://api.example.com/openapi.json
# Specify MCP server port (default: 8080)
npx mcpify --spec api-spec.yaml --port 9000
# Enable debug logging for request/response inspection
npx mcpify --spec api-spec.yaml --log-level debug
[!NOTE]
![]()
npx mcpify
will work once this package is published, which will happen imminently.
Example output:
[INFO] Loading OpenAPI specification from api-spec.yaml
[INFO] Validating OpenAPI document
[INFO] Found 8 endpoints to convert
[INFO] Converting GET /users → query tool "listUsers"
[INFO] Converting GET /users/{id} → query tool "getUserById"
[INFO] Converting POST /users → mutation tool "createUser"
[INFO] Converting PUT /users/{id} → mutation tool "updateUser"
[INFO] Converting DELETE /users/{id} → mutation tool "deleteUser"
[INFO] Converting GET /products → query tool "listProducts"
[INFO] Converting GET /products/{id} → query tool "getProductById"
[INFO] Converting POST /orders → mutation tool "createOrder"
[INFO] MCP proxy server started at http://localhost:8080
[INFO] MCP debugging interface available at http://localhost:8080/debug
Architecture
MCPify follows a real-time proxy architecture:
- Parser
: Loads and validates the OpenAPI specification
- Mapper
: Converts API endpoints to MCP tools and resources dynamically
- Proxy
: Routes MCP tool calls to the appropriate REST endpoints
- Server
: Exposes the MCP interface to clients
Conversion Rules
OpenAPI to MCP Mapping
Status | OpenAPI Element | MCP Element | Conversion Notes |
---|---|---|---|
operationId | Tool name | Falls back to path+method if not specified | |
summary +description | Tool description | Combined with configurable formatting | |
Parameters + request body | Tool inputSchema | Converted to JSON Schema | |
deprecated flag | annotations.deprecated | Direct mapping | |
HTTP method | Tool annotations | Maps to readOnlyHint , destructiveHint , etc. | |
tags | annotations.tags | Used for categorization | |
responses schemas | Tool result handling | For typed result processing | |
security | Authentication | Security scheme mapping | |
examples | Usage examples | Added to tool descriptions | |
Related endpoints | annotations.relatedTools | For complex workflows |
HTTP Method Mappings
HTTP Method | Tool Annotations | Semantic Meaning |
---|---|---|
GET | {"readOnlyHint": true} | Non-destructive query operation |
POST | {"readOnlyHint": false, "destructiveHint": false} | Creation operation |
PUT | {"readOnlyHint": false, "destructiveHint": true, "idempotentHint": true} | Idempotent update |
PATCH | {"readOnlyHint": false, "destructiveHint": true} | Partial update |
DELETE | {"readOnlyHint": false, "destructiveHint": true} | Resource deletion |
Resource Generation
Endpoints are automatically converted to MCP resources when:
- The endpoint is a GET operation
- And either:
- Has no parameters, or
- Has only path parameters (for resource templates)
Schema Compatibility
[!IMPORTANT] MCPify handles the differences between OpenAPI schemas and MCP’s JSON Schema requirements.
Schema Differences
OpenAPI Schema | MCP Schema | Handling Strategy |
---|---|---|
Uses JSON Schema subset | Uses standard JSON Schema | Convert and validate |
Has OpenAPI extensions | No extensions | Remove or map appropriately |
Relies on $ref | Requires inline schemas | Resolve all references |
Has nullable (OAS 3.0) | Uses type: ["null", ...] | Convert format |
[!TIP]
The easiest way to deal with the differences in OpenAPI Schema is to stick to the version of JSON Schema supported by OpenAPI 3.1. That minimizes the need for automatic conversions, which rely on heuristics.
[!IMPORTANT]
If you don’t like the automatic conversions, you can use the
x-mcpify
extension to provide your own schema.
Type Mappings
OpenAPI Type | Format | MCP JSON Schema Type | Format |
---|---|---|---|
string | various | string | preserved |
integer | int32 /int64 | integer | normalized |
number | float /double | number | normalized |
boolean | n/a | boolean | preserved |
array | n/a | array | preserved |
object | n/a | object | preserved |
Configuration
Using x-mcpify Extensions and Proxy Configuration
Configure custom behavior using the x-mcpify
extension at different levels in your OpenAPI spec:
- Root level - Global configuration
- Path level - Endpoint-specific settings
- Operation level - Fine-grained control
# Root level configuration
x-mcpify:
templates:
default:
description: "{summary} ({description})"
proxy:
timeout: 30 # Request timeout in seconds
retries: 3 # Number of retry attempts
caching:
enabled: true
ttl: 300 # Cache TTL in seconds
# Path level configuration
paths:
/users:
x-mcpify:
include: [tools, resources]
proxy:
timeout: 60 # Override timeout for this path
# Operation level configuration
/users/{id}:
get:
x-mcpify:
operationId: "user_by_id" # Override name
annotations: # Custom annotations
readOnlyHint: false # Override default
proxy:
caching: # Operation-specific cache settings
ttl: 600
Alternatively, you can provide proxy-specific configuration via command-line flags:
# Configure proxy timeout and retries
mcpify --spec api-spec.yaml --timeout 60 --retries 3
# Enable response caching
mcpify --spec api-spec.yaml --cache-ttl 300
# Set custom headers for all proxied requests
mcpify --spec api-spec.yaml --header "User-Agent: MCPify/1.0" --header "X-Custom: Value"
Opting Out
Disable automatic conversion for specific endpoints:
paths:
/internal/metrics:
get:
x-mcpify: false # Disable completely
/users/{id}:
get:
x-mcpify:
map: ["tool"] # Only create tool, not resource
Examples
Basic Endpoint Conversion
OpenAPI Input:
paths:
/users/{id}:
get:
operationId: getUserById
summary: Get user by ID
description: Retrieves a user by their unique identifier
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
200:
description: User found
content:
application/json:
schema:
$ref: "#/components/schemas/User"
Dynamically Generated MCP Tool:
{
"name": "getUserById",
"description": "Get user by ID - Retrieves a user by their unique identifier",
"inputSchema": {
"type": "object",
"required": ["id"],
"properties": {
"id": {
"type": "string",
"description": "User's unique identifier"
}
}
},
"annotations": {
"readOnlyHint": true,
"sourceEndpoint": "/users/{id}"
}
}
Complex Scenario: Authentication
OpenAPI Input with Security:
security:
- apiKey: []
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
paths:
/secure/resource:
get:
operationId: getSecureResource
summary: Get a secure resource
Dynamically Generated MCP Tool with Auth:
{
"name": "getSecureResource",
"description": "Get a secure resource - Requires API Key authentication",
"inputSchema": {
"type": "object",
"required": ["apiKey"],
"properties": {
"apiKey": {
"type": "string",
"description": "API Key for authentication"
}
}
},
"annotations": {
"readOnlyHint": true,
"authentication": {
"type": "apiKey",
"location": "header",
"name": "X-API-Key"
}
}
}
MCP Proxy Features
Dynamic Request Handling
MCPify intelligently converts between MCP tool calls and REST API requests:
Request Transformation: Converts MCP tool arguments to appropriate query parameters, path parameters, headers, and request bodies based on the OpenAPI spec
Response Transformation: Converts REST API responses back to MCP tool results with proper content formatting
Error Handling: Maps HTTP error codes to meaningful MCP error responses with appropriate status codes and error messages
Authentication Forwarding: Securely forwards authentication tokens from MCP clients to the underlying REST API
Debugging and Monitoring
MCPify includes a web-based debugging interface at /debug
that provides:
- Real-time request/response logging
- Tool mapping visualization
- Performance metrics for proxied requests
- Schema conversion inspection
Integration with AI Agents
MCPify makes it easy to connect existing REST APIs to AI agents that support the MCP protocol, effectively turning any API into a tool the agent can use:
# Start MCPify proxy to convert Stripe API to MCP
mcpify --spec https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
--header "Authorization: Bearer sk_test_123"
--port 8080
# Connect your AI agent to the MCP proxy
ai-agent --mcp-server http://localhost:8080
Now your AI agent can directly use Stripe API endpoints as MCP tools without any additional implementation.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT
MCPify
Project Details
- wycats/mcpify
- Last Updated: 4/30/2025
Recomended MCP Servers
Local Model Context Protocol Server with BirdNet-Pi integration
Bringing the bankless onchain API to MCP

MCP server for working with 3rd party library documentation
MCP server for code collection and documentation
MCP Server to make line-based edits to a file.
Claude can perform Web Search | Exa with MCP (Model Context Protocol)
MCP server for interacting with Prometheus
MCP Server for SQL Server using node-mssql
Zendesk MCP Server
MCP Server with TMDB