mekayelanik/openapi-mcp-server repository overview

⁠OpenAPI MCP Server

⁠Multi-Architecture Docker Image for OpenAPI Integration

⁠Table of Contents

• Overview⁠
• Supported Architectures⁠
• Available Tags⁠
• Quick Start⁠
• Configuration⁠
• MCP Client Configuration⁠
• Network Configuration⁠
• Updating⁠
• Troubleshooting⁠
• Additional Resources⁠
• Support & License⁠

⁠😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

⁠

⁠Overview

OpenAPI MCP Server is a Model Context Protocol server that bridges OpenAPI specifications with LLMs (Large Language Models). It loads OpenAPI specs from URLs or local files and exposes the API operations as MCP tools. Built on Alpine Linux for minimal footprint and maximum security, wrapped with mcp-proxy for HTTP/SSE/WebSocket transport.

⁠Key Features

• OpenAPI Spec Loading - Load specs from URL or local file path
• Multiple Authentication Types - Supports none, basic, bearer, api_key, and AWS Cognito
• Multi-Architecture Support - Native support for x86-64 and ARM64
• Multiple Transport Protocols - HTTP, SSE, and WebSocket support
• Secure by Design - Alpine-based with minimal attack surface, HAProxy with TLS/CORS support
• High Performance - ZSTD compression for faster deployments
• Production Ready - Stable releases with comprehensive testing
• Easy Configuration - Simple environment variable setup

⁠Supported Architectures

⁠Available Tags

⁠System Requirements

• Docker Engine: 23.0+
• RAM: Minimum 512MB
• CPU: Single core sufficient

⁠Quick Start

⁠Docker Compose (Recommended)

services:
  openapi-mcp-server:
    image: mekayelanik/openapi-mcp-server:stable
    container_name: openapi-mcp-server
    restart: unless-stopped
    ports:
      - "8050:8050"
    environment:
      - PORT=8050
      - INTERNAL_PORT=38011
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Dhaka
      - PROTOCOL=SHTTP
      - ENABLE_HTTPS=false
      - HTTP_VERSION_MODE=auto
      # OpenAPI configuration
      - API_NAME=my-api
      - API_BASE_URL=https://api.example.com
      - API_SPEC_URL=https://api.example.com/openapi.json
      # - API_SPEC_PATH=/specs/openapi.json
      # Authentication (choose one)
      - AUTH_TYPE=none
      # - AUTH_TYPE=bearer
      # - AUTH_TOKEN=your-bearer-token
      # - AUTH_TYPE=api_key
      # - AUTH_API_KEY=your-api-key
      # - AUTH_API_KEY_NAME=X-API-Key
      # - AUTH_API_KEY_IN=header
      # Optional: require Bearer token auth at HAProxy layer
      # - API_KEY=replace-with-strong-secret
    hostname: openapi-mcp-server
    domainname: local

Deploy:

docker compose up -d
docker compose logs -f openapi-mcp-server

⁠Docker CLI

docker run -d \
  --name=openapi-mcp-server \
  --restart=unless-stopped \
  -p 8050:8050 \
  -e PORT=8050 \
  -e INTERNAL_PORT=38011 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Dhaka \
  -e PROTOCOL=SHTTP \
  -e ENABLE_HTTPS=false \
  -e HTTP_VERSION_MODE=auto \
  -e API_NAME=my-api \
  -e API_BASE_URL=https://api.example.com \
  -e API_SPEC_URL=https://api.example.com/openapi.json \
  -e AUTH_TYPE=none \
  mekayelanik/openapi-mcp-server:stable

⁠Access Endpoints

When HTTPS is enabled (ENABLE_HTTPS=true), use TLS endpoints:

⁠Configuration

⁠Environment Variables

⁠Container Configuration

⁠API Configuration

⁠Authentication Configuration

⁠AWS Cognito Authentication

⁠Server Configuration

⁠Metrics & Monitoring

⁠Graceful Shutdown

⁠TLS / HTTPS Configuration

⁠Security Configuration

⁠HTTPS and HTTP Version Notes

• If ENABLE_HTTPS=true and cert files are missing, the container auto-generates a self-signed certificate.
• If TLS_CERT_PATH and TLS_KEY_PATH exist, they are merged into TLS_PEM_PATH and used directly.
• HTTP_VERSION_MODE=h3 (or auto) enables HTTP/3 only when HAProxy build includes QUIC; otherwise it safely falls back.

⁠API Key Authentication Notes

• Set API_KEY to enforce authentication at reverse proxy level.
• Expected header format: Authorization: Bearer <API_KEY>.
• Localhost health checks remain accessible for liveness/readiness.

⁠Rate Limiting and IP Access Control

• Rate limiting: Set RATE_LIMIT=100 to allow 100 requests per RATE_LIMIT_PERIOD (default 10s) per IP. Exceeding the limit returns HTTP 429 with a Retry-After header.
• Connection limiting: Set MAX_CONNECTIONS_PER_IP=50 to cap concurrent connections per IP. Exceeding returns HTTP 429.
• IP blocklist: Set IP_BLOCKLIST=192.0.2.0/24,198.51.100.5 to block specific IPs/CIDRs. Blocked IPs receive HTTP 403.
• IP allowlist: Set IP_ALLOWLIST=10.0.0.0/8,192.168.1.0/24 to allow only listed IPs/CIDRs. All others receive HTTP 403. Localhost is always allowed.
• All features default to disabled. Combine as needed — blocklist is checked before allowlist.

⁠User & Group IDs

Find your IDs and set them to avoid permission issues:

id username
# uid=1000(user) gid=1000(group)

⁠Timezone Examples

- TZ=Asia/Dhaka        # Bangladesh
- TZ=America/New_York  # US Eastern
- TZ=Europe/London     # UK
- TZ=UTC               # Universal Time

⁠Memory & Concurrency Tuning

This image embeds mcp-proxy (sparfenyuk/mcp-proxy) as the stdio↔HTTP bridge.

• MCP_PROXY_STATELESS=false (default): one stdio backend child is shared across all MCP sessions, JSON-RPC-id-multiplexed. Minimal memory.
• MCP_PROXY_STATELESS=true: per-request transport instance. Use only when full session isolation is required.
• HAPROXY_FRONTEND_MAXCONN / HAPROXY_SERVER_MAXCONN: HAProxy-level caps. Defaults 64/16.
• WebSocket transport is no longer supported (mcp-proxy upstream does not implement it).

Root cause: supergateway 3.4.3 stateless mode leaks child processes (supercorp-ai/supergateway#108).

⁠MCP Client Configuration

⁠Transport Support

⁠VS Code (Cline/Roo-Cline)

Configure in .vscode/settings.json:

{
  "mcp.servers": {
    "openapi-mcp": {
      "url": "http://host-ip:8050/mcp",
      "transport": "http"
    }
  }
}

⁠Claude Desktop App/Claude Code

With API_KEY:

claude mcp add-json openapi-mcp '{"type":"http","url":"http://localhost:8050/mcp","headers":{"Authorization":"Bearer <YOUR_API_KEY>"}}'

Without API_KEY:

claude mcp add-json openapi-mcp '{"type":"http","url":"http://localhost:8050/mcp"}'

⁠Codex CLI

Configure in ~/.codex/config.json:

{
  "mcpServers": {
    "openapi-mcp": {
      "transport": "http",
      "url": "http://host-ip:8050/mcp"
    }
  }
}

⁠Codeium (Windsurf)

Configure in .codeium/mcp_settings.json:

{
  "mcpServers": {
    "openapi-mcp": {
      "transport": "http",
      "url": "http://host-ip:8050/mcp"
    }
  }
}

⁠Cursor

Configure in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "openapi-mcp": {
      "transport": "http",
      "url": "http://host-ip:8050/mcp"
    }
  }
}

⁠Testing Configuration

Verify with MCP Inspector⁠:

npm install -g @modelcontextprotocol/inspector
mcp-inspector http://host-ip:8050/mcp

⁠Network Configuration

⁠Comparison

⁠Bridge Network (Default)

services:
  openapi-mcp-server:
    image: mekayelanik/openapi-mcp-server:stable
    ports:
      - "8050:8050"

Benefits: Container isolation, easy setup, works everywhere Access: http://localhost:8050/mcp

⁠Host Network (Linux Only)

services:
  openapi-mcp-server:
    image: mekayelanik/openapi-mcp-server:stable
    network_mode: host

Benefits: Maximum performance, no NAT overhead, no port mapping needed Considerations: Linux only, shares host network namespace Access: http://localhost:8050/mcp

⁠MACVLAN Network (Advanced)

services:
  openapi-mcp-server:
    image: mekayelanik/openapi-mcp-server:stable
    mac_address: "AB:BC:CD:DE:EF:01"
    networks:
      macvlan-net:
        ipv4_address: 192.168.1.100

networks:
  macvlan-net:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

Benefits: Dedicated IP, direct LAN access Considerations: Linux only, requires additional setup Access: http://192.168.1.100:8050/mcp

⁠Updating

⁠Docker Compose

docker compose pull
docker compose up -d
docker image prune -f

⁠Docker CLI

docker pull mekayelanik/openapi-mcp-server:stable
docker stop openapi-mcp-server && docker rm openapi-mcp-server
# Run your original docker run command
docker image prune -f

⁠One-Time Update with Watchtower

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once \
  openapi-mcp-server

⁠Troubleshooting

⁠Pre-Flight Checklist

• Docker Engine 23.0+
• Port 8050 available
• Sufficient startup time (ARM devices)
• Latest stable image
• Correct configuration

⁠Common Issues

⁠Container Won't Start

# Check Docker version
docker --version

# Verify port availability
sudo netstat -tulpn | grep 8050

# Check logs
docker logs openapi-mcp-server

⁠Permission Errors

# Get your IDs
id $USER

# Update configuration with correct PUID/PGID
# Fix volume permissions if needed
sudo chown -R 1000:1000 /path/to/volume

⁠Client Cannot Connect

# Test connectivity
curl http://localhost:8050/mcp
curl http://host-ip:8050/mcp
curl -k https://localhost:8050/mcp
curl -k https://host-ip:8050/mcp

# Check firewall
sudo ufw status

# Verify container
docker inspect openapi-mcp-server | grep IPAddress

⁠Slow ARM Performance

• Wait 30-60 seconds after start
• Monitor: docker logs -f openapi-mcp-server
• Check resources: docker stats openapi-mcp-server
• Use faster storage (SSD vs SD card)

⁠Debug Information

When reporting issues, include:

# System info
docker --version && uname -a

# Container logs
docker logs openapi-mcp-server --tail 200 > logs.txt

# Container config
docker inspect openapi-mcp-server > inspect.json

⁠Additional Resources

⁠Documentation

• OpenAPI MCP Upstream⁠
• PyPI Package⁠
• MCP Inspector⁠

⁠Docker Resources

• Docker Compose Best Practices⁠
• Docker Networking⁠
• Docker Security⁠

⁠Monitoring

• Diun - Update Notifier⁠
• Watchtower⁠

⁠😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

⁠

⁠Support & License

⁠Getting Help

Docker Image Issues:

• GitHub: openapi-mcp-docker/issues⁠

OpenAPI MCP Issues:

• GitHub: awslabs/mcp/issues⁠

⁠Contributing

We welcome contributions:

1. Report bugs via GitHub Issues
2. Suggest features
3. Improve documentation
4. Test beta releases

⁠License

GPL License. See LICENSE⁠ for details.

OpenAPI MCP server has its own license - see upstream repository⁠.