OpenAPI MCP

Overview

OpenAPI MCP is a Model Context Protocol server that enables AI agents to interact with any REST API using OpenAPI (Swagger) specifications. It automatically generates tool definitions from OpenAPI schemas, allowing agents to make API calls without manual configuration.

This server is particularly powerful for integrating AI agents with existing APIs — whether internal services, third-party APIs, or public APIs. The agent can discover available endpoints, understand required parameters, and execute API calls with proper authentication.

Features

• OpenAPI Specification Support: Load any OpenAPI 3.x specification
• Automatic Tool Generation: Convert API endpoints to MCP tools
• Schema Validation: Validate requests against OpenAPI schemas
• Authentication Support: API keys, OAuth2, Bearer tokens, Basic auth
• Request/Response Inspection: See full request and response details
• Dynamic Discovery: Agents can explore available endpoints
• Multi-API Support: Load multiple OpenAPI specifications

Installation

npx -y @modelcontextprotocol/server-openapi

Or install globally:

npm install -g @modelcontextprotocol/server-openapi

Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openapi"],
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
        "OPENAPI_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Tool	Description
list_endpoints	List all available API endpoints
describe_endpoint	Get detailed information about an endpoint
call_endpoint	Make an API request to a specific endpoint
load_spec	Load a new OpenAPI specification
reload	Reload the current specification

Usage Examples

Load an OpenAPI Specification

from mcp import ClientSession, StdioClientTransport
import asyncio

async def load_api():
    transport = StdioClientTransport(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-openapi"]
    )
    
    async with ClientSession(transport) as session:
        await session.initialize()
        
        # Load a specification
        result = await session.call_tool(
            "load_spec",
            arguments={
                "url": "https://api.github.com/openapi.json",
                "auth": {"type": "bearer", "token": "your-token"}
            }
        )
        print(f"Loaded {result.endpoints_count} endpoints")

List Available Endpoints

async def list_endpoints():
    result = await session.call_tool("list_endpoints")
    
    for endpoint in result.endpoints:
        print(f"{endpoint.method} {endpoint.path}")
        print(f"  Summary: {endpoint.summary}")
        print(f"  Operation ID: {endpoint.operation_id}")

Call an Endpoint

async def call_api():
    # Get details about an endpoint
    details = await session.call_tool(
        "describe_endpoint",
        arguments={"operation_id": "list_repos"}
    )
    
    print(f"Parameters: {details.parameters}")
    print(f"Required: {details.required}")
    
    # Call the endpoint
    result = await session.call_tool(
        "call_endpoint",
        arguments={
            "operation_id": "list_repos",
            "path_params": {"username": "octocat"},
            "query_params": {"sort": "updated"},
            "headers": {"Accept": "application/vnd.github.v3+json"}
        }
    )
    
    print(f"Response: {result.response}")

Working with Authentication

# API Key authentication
await session.call_tool(
    "call_endpoint",
    arguments={
        "operation_id": "get_user",
        "headers": {"X-API-Key": "your-api-key"}
    }
)

# Bearer token authentication
await session.call_tool(
    "call_endpoint",
    arguments={
        "operation_id": "get_profile",
        "headers": {"Authorization": "Bearer your-token"}
    }
)

# Basic authentication
await session.call_tool(
    "call_endpoint",
    arguments={
        "operation_id": "get_account",
        "headers": {"Authorization": "Basic base64(user:pass)"}
    }
)

Advanced Features

Multiple API Specifications

# Load multiple APIs
await session.call_tool(
    "load_spec",
    arguments={"url": "https://api.service1.com/openapi.json"}
)

await session.call_tool(
    "load_spec",
    arguments={"url": "https://api.service2.com/openapi.json"}
)

# List all loaded specs
specs = await session.call_tool("list_specs")

Dynamic API Discovery

async def discover_api(base_url: str):
    # Try common OpenAPI locations
    locations = [
        f"{base_url}/openapi.json",
        f"{base_url}/swagger.json",
        f"{base_url}/v3/api_docs",
        f"{base_url}/api-docs/openapi.json"
    ]
    
    for url in locations:
        try:
            result = await session.call_tool("load_spec", {"url": url})
            if result.success:
                return result
        except:
            continue
    return None

API Testing and Debugging

async def test_endpoint(operation_id: str, test_data: dict):
    # Get endpoint schema
    schema = await session.call_tool(
        "describe_endpoint",
        arguments={"operation_id": operation_id}
    )
    
    # Validate test data against schema
    validation = validate_against_schema(test_data, schema)
    
    if validation.valid:
        # Make the call
        result = await session.call_tool(
            "call_endpoint",
            arguments={
                "operation_id": operation_id,
                **test_data
            }
        )
        return result
    else:
        return {"error": validation.errors}

Examples

GitHub API Integration

# Load GitHub API spec
await session.call_tool(
    "load_spec",
    arguments={"url": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"}
)

# List user repos
repos = await session.call_tool(
    "call_endpoint",
    arguments={
        "operation_id": "repos/list_for_authenticated_user",
        "query_params": {"per_page": 10}
    }
)

# Create a new issue
issue = await session.call_tool(
    "call_endpoint",
    arguments={
        "operation_id": "issues/create",
        "path_params": {"owner": "my-org", "repo": "my-repo"},
        "body": {"title": "New issue", "body": "Issue description"}
    }
)

Stripe API Integration

await session.call_tool(
    "load_spec",
    arguments={"url": "https://raw.githubusercontent.com/stripe/openapi/master/openapi.yaml"}
)

# List customers
customers = await session.call_tool(
    "call_endpoint",
    arguments={
        "operation_id": "v1.customers.list",
        "headers": {"Authorization": "Bearer sk_test_xxx"}
    }
)

# Create a charge
charge = await session.call_tool(
    "call_endpoint",
    arguments={
        "operation_id": "v1.charges.create",
        "body": {
            "amount": 2000,
            "currency": "usd",
            "source": "tok_visa",
            "description": "Example charge"
        },
        "headers": {"Authorization": "Bearer sk_test_xxx"}
    }
)

Pros

• ✅ Works with any OpenAPI-compliant API
• ✅ Automatic tool generation from specs
• ✅ No manual endpoint configuration needed
• ✅ Built-in schema validation
• ✅ Multiple authentication methods
• ✅ Great for API exploration
• ✅ Reduces integration time

Cons

• ❌ Requires OpenAPI specification availability
• ❌ Some APIs don't publish OpenAPI specs
• ❌ Complex schemas may have limitations
• ❌ Authentication setup per API
• ❌ Rate limits depend on target API

When to Use

• API integration — Connect agents to REST APIs
• Internal tools — Access company APIs and services
• Third-party APIs — Integrate with external services
• API exploration — Discover available endpoints
• Rapid prototyping — Quickly test API integrations
• Multi-service workflows — Chain multiple API calls

Resources

• OpenAPI Specification
• GitHub Repository
• Swagger UI
• API Blueprint