Proposal: OpenAPI to MCP Converter - Bridging the Gap Between Human-Readable and AI-Ready APIs

[aarora79]

Proposal: OpenAPI to MCP Converter - Bridging the Gap Between Human-Readable and AI-Ready APIs

Executive Summary

I propose establishing the OpenAPI to MCP Converter as a critical tool in the AI ecosystem that addresses a fundamental challenge: most API documentation is optimized for human consumption but fails to meet the requirements for reliable AI agent operation. This tool evaluates, enhances, and converts OpenAPI specifications into production-ready Model Context Protocol (MCP) servers, ensuring APIs are truly AI-ready.

The Problem We're Solving

The AI-Readiness Gap

As enterprises transition toward AI integration, we've identified a critical disconnect:

Human developers can work with minimal API documentation because they:

• Leverage domain expertise and tribal knowledge
• Make educated guesses about missing parameters
• Understand implicit business logic
• Fill in documentation gaps through experience

AI agents struggle with the same documentation because they:

• Cannot infer missing information reliably
• May hallucinate parameters and behaviors
• Require explicit, comprehensive documentation
• Need structured, unambiguous specifications

Real-World Example

Consider this typical API specification that looks acceptable to developers:

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users
      responses:
        '200':
          description: Success

Human interpretation: "Oh, this probably returns a list of users, might have pagination, probably needs auth."

AI agent interpretation: Unknown - proceeds to hallucinate parameters, response formats, and authentication requirements

The Consequences

When incomplete API specifications are converted directly to AI tools:

• Unpredictable behavior: AI agents guess at missing information
• Failed integrations: Tools break when assumptions prove incorrect
• Security risks: Missing authentication documentation leads to improper access
• Poor user experience: Inconsistent and unreliable AI assistance

Our Solution

The OpenAPI to MCP Converter addresses this gap through a multi-stage pipeline:

1. AI-Powered Evaluation

Uses LLMs to analyze API specifications across multiple dimensions:

• Completeness (1-5 score): Missing descriptions, parameters, schemas
• AI Readiness (1-5 score): Suitability for AI agent consumption
• Security: Authentication and authorization assessment
• Best Practices: OpenAPI specification compliance

2. Quality Enforcement

• Threshold Requirements: Both completeness and AI readiness must score ≥3/5
• Blocks Generation: Prevents creating unreliable MCP servers from poor specs
• Actionable Feedback: Specific suggestions for improvement

3. Intelligent Enhancement

When specs meet quality thresholds, the tool:

• Enhances descriptions and documentation
• Adds missing examples and schemas
• Documents pagination and filtering patterns
• Improves error response documentation

4. MCP Server Generation

Creates production-ready implementations including:

• Fully functional Python-based MCP server
• Ready-to-use client for testing
• Comprehensive documentation
• All necessary dependencies

Proven Results

Success Story: Space Mission API

• Completeness: 4/5
• AI Readiness: 5/5
• Result: Fully functional MCP server generated

Failure Case: Minimal Users API

• Completeness: 1/5
• AI Readiness: 1/5
• Result: Generation blocked with specific improvement recommendations

Why This Repository Matters

1. Enterprise AI Readiness

• Bridges the gap between existing APIs and AI requirements
• Provides clear metrics for API AI-readiness
• Enables systematic improvement of API documentation

2. Developer Productivity

• Automates MCP server creation from OpenAPI specs
• Saves hours of manual implementation work
• Provides immediate feedback on documentation quality

3. Quality Assurance

• Prevents deployment of unreliable AI tools
• Ensures consistent documentation standards
• Identifies security and completeness gaps

4. Ecosystem Growth

• Accelerates MCP adoption
• Standardizes AI-ready API practices
• Builds bridge between traditional APIs and AI agents

Technical Implementation

Architecture

• Multi-stage pipeline: Load → Evaluate → Enhance → Generate
• LLM Integration: Supports Amazon Bedrock and Anthropic Claude
• Comprehensive reporting: Evaluation scores, usage tracking, cost analysis

Key Features

• Supports OpenAPI 3.0 and Swagger 2.0
• Generates Python-based MCP servers
• Includes testing infrastructure (stub servers, clients)
• Provides detailed evaluation reports

Future Vision

This tool represents the first step in a larger mission to make all APIs AI-ready. Future enhancements could include:

• Support for extremely large API specifications
• Additional language targets beyond Python
• Integration with API documentation tools
• Automated enhancement suggestions

Discussion Points

1. What other API specification formats should we support?
2. How can we better integrate with existing API development workflows?
3. What additional quality metrics would be valuable for AI readiness?

---

The difference between human-readable and AI-ready documentation is the difference between APIs that work sometimes and APIs that work reliably. Let's bridge this gap together.

What are your thoughts on this proposal? How can we make APIs truly AI-ready across the ecosystem?

[mzayats]

Aren't there multiple projects for OpenAPI to MCP conversion?
Something like https://jedisct1.github.io/openapi-mcp/

[aarora79]

There are similar solutions yes, btw https://github.com/jedisct1/openapi-mcp is archived so not sure what is the future with that one, but then there is this one as well https://github.com/higress-group/openapi-to-mcpserver.
This particular solution also focusses on the AI Readiness aspect (i.e. does the OpenAPI spec have enough details in it to make a good MCP server out of it for example) in addition to the OpenAPI to MCP server conversion piece. For example https://github.com/agentic-community/openapi-to-mcp/blob/main/examples/results/anthropic/minimal_users_api/summary_20250720_154803.md and https://github.com/agentic-community/openapi-to-mcp/blob/main/examples/results/anthropic/sample_api/summary_20250718_150544.md.