Njoodd/dynamic-openapi-mcp

Dynamic OpenAPI MCP Server

A Model Context Protocol (MCP) server that automatically discovers and consumes OpenAPI specifications, enabling AI Agents to interact with any API dynamically.

Overview

This MCP server pulls OpenAPI specifications from a collection endpoint and automatically generates tools for AI Agents to execute API requests. It's designed to be API-agnostic with no hardcoded API details.

Architecture

┌─────────────────┐    MCP     ┌──────────────────┐    HTTP     ┌─────────────────┐
│  Claude Desktop │ ←────────→ │ Dynamic OpenAPI  │ ←────────→  │ OpenAPI Spec    │
│                 │            │ MCP Server       │             │ Server          │
└─────────────────┘            └──────────────────┘             └─────────────────┘

Quick Start

Local Development (STDIO Transport)

Run directly on your system for local development:

1. Setup environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   

2. Start the MCP server:

   python run_server.py
   

3. MCP Client Example: Configure Claude Desktop: Add to your MCP settings:

   {
     "mcpServers": {
       "dynamic-openapi-mcp": {
         "command": "python",
         "args": ["/absolute/path/to/your/project/run_server.py"]
       }
     }
   }
   

Production Deployment (HTTP Transport)

Use Docker for production/remote deployment:

1. Start both services:

   docker-compose up -d
   

2. MCP Client Example: Configure Claude Desktop: Add to your MCP settings:

   {
     "mcpServers": {
       "dynamic-openapi-mcp": {
         "command": "curl",
         "args": ["-X", "POST", "http://localhost:8000/mcp/"]
       }
     }
   }
   

3. Verify deployment:

   # Check MCP server
   curl http://localhost:8000/mcp/
   
   # Check OpenAPI collections
   curl http://localhost:8001/
   

Available Tools

Once running, MCP Server will expose these tools:

• search_api_collections - Find APIs by capability or description
• get_openapi_spec - Retrieve full OpenAPI specification
• get_auth_from_spec - Get authentication requirements
• execute_api - Execute API requests with parameters

Configuration

Environment Variables

Transport Modes

Transport is automatically detected:

• STDIO: When running Python directly on host system (local development)
• HTTP: When running in Docker container (production deployment)

Development

Project Structure

├── src/                    # Source modules
│   ├── api_client.py      # HTTP client for API requests
│   ├── api_collection.py  # Collection loading and models
│   └── authentication.py # Auth handling
├── server.py              # Main MCP server
├── run_server.py          # Server launcher
├── docker-compose.yml     # Production deployment
└── requirements.txt       # Python dependencies

Local vs Docker Development

Local Development (Recommended):

• Run Python directly on your system
• Uses STDIO transport for direct communication
• Faster development cycle, easier debugging

Docker Development:

• Only useful for testing production HTTP deployment
• Cannot use STDIO transport with Docker
• Use docker-compose up to test HTTP transport locally

Testing Different Transports

# Local development (STDIO) - run directly
python run_server.py

# Production deployment (HTTP) - use Docker
docker-compose up

Dependencies

• FastMCP: MCP server framework
• Requests: HTTP client
• PyYAML: YAML parsing
• Pydantic: Data validation

Troubleshooting

Connection Issues

1. Development mode: Ensure the server starts without errors
2. Production mode: Check if port 8000 is accessible
3. Claude Desktop: Verify MCP configuration matches your transport mode

Common Commands

# Check server logs
docker-compose logs dynamic-openapi-mcp

# Restart services
docker-compose restart

# Stop services
docker-compose down

For detailed deployment information, see .