REST-to-MCP Adapter

A Python library for converting REST API specifications into MCP (Model Context Protocol) tools for AI agents.

Transform any REST API specification into tools that Claude, GPT, and other LLM-powered agents can use.

Supported Formats:

• OpenAPI 3.x (JSON, YAML)
• Swagger 2.x (JSON, YAML)
• OpenAPI Actions format (JSON)

⚠️ Beta Status: This library is currently in beta (v0.1.0). The core functionality is stable and production-ready, but the API may evolve based on community feedback. We welcome early adopters and contributors!

---

🚀 Quick Start

Simple Approach (Recommended for Most Users)

from adapter import ToolRegistry, MCPServer, APIExecutor, BearerAuth

# Create registry from OpenAPI spec (includes endpoints)
registry = ToolRegistry.create_from_openapi(
    "https://api.example.com/openapi.json"
)

# Set up executor
executor = APIExecutor(
    base_url="https://api.example.com",
    auth=BearerAuth(token="your-token")
)

# Create server - endpoints are in the registry!
server = MCPServer(
    name="My API Server",
    version="1.0.0",
    tool_registry=registry,
    executor=executor
    # No endpoints parameter needed!
)
server.run()

For advanced usage and individual step control, see Detailed Usage below.

---

📦 Installation

Stable Release

pip install rest-to-mcp-adapter

Beta Release (Latest Features)

To install the latest beta version with cutting-edge features:

pip install --pre rest-to-mcp-adapter

Or install a specific beta version:

pip install rest-to-mcp-adapter==0.2.0b1

From Source (For Development)

git clone https://github.com/pawneetdev/rest-to-mcp-adapter.git
cd rest-to-mcp-adapter
pip install -e .

Dependencies

Core dependencies (automatically installed):

• pydantic>=2.0.0 - Data validation and modeling
• pyyaml>=6.0 - YAML parsing
• requests>=2.31.0 - HTTP client

Optional dependencies:

• langchain-community>=0.0.20 - Enhanced OpenAPI validation (install with: pip install rest-to-mcp-adapter[langchain])

---

✨ Key Features

🔄 Specification Ingestion

• Multiple formats: OpenAPI 3.x, Swagger 2.x, OpenAPI Actions
• JSON & YAML: Full support for both formats
• Load from anywhere: URL, file path, or raw content
• Auto-detection: Automatically determines input type and format
• $ref dereferencing: Resolves all JSON pointer references

🛠️ MCP Tool Generation

• Automatic conversion: OpenAPI endpoints → MCP tools
• Smart naming: 64-character limit with intelligent truncation
• Auth filtering: Automatically hides auth parameters from users
• Hybrid approach: Defaults + auto-detection + custom overrides

🔐 Authentication Support

• Built-in handlers: API Key, Bearer, Basic, OAuth2
• Custom handlers: Easy to implement your own
• Automatic parameter filtering: Auth params hidden from tool schemas
• Conditional auth: Only applies to endpoints that require it

⚡ Runtime Execution

• Direct API calls: Execute REST requests from canonical endpoints
• Retry logic: Exponential backoff for failed requests
• Error handling: Comprehensive error types and messages
• Response processing: JSON, text, and binary support