⚡ MCPO Configuration Manager

Web UI for managing MCPO (Model Context Protocol to OpenAPI) servers.

Features

• 🎨 Dual input modes - Form-based UI and JSON editor
• 🔄 Auto-reload - Config changes automatically restart MCPO (built-in watcher)
• 🐳 Docker-ready - Single container, single docker-compose up command
• ⚡ Universal runtime - Supports uvx, npx, and docker commands
• 🛡️ Safe defaults - Always maintains at least one server (prevents crashes)
• 🔐 Authentication - Optional HTTP Basic Auth via Caddy + MCPO API key protection

Quick Start

# 1. Set up environment variables
cp .env.example .env
# Edit .env and set MCPO_API_KEY (required)

# 2. Start the service
docker-compose up -d

# 3. Access the UI
open http://localhost

# 4. View MCPO API docs
open http://localhost:8000/<server-name>/docs

What you get:

• UI: http://localhost (port 80)
• MCPO API: http://localhost:8000
• Default time server included (can be deleted/replaced)
• Auto-restart on config changes

Server Types

The UI supports three types of MCP servers:

Configuration Examples

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "docker-example": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/time"]
    }
  }
}

{
  "mcpServers": {
    "remote-sse": {
      "type": "sse",
      "url": "http://127.0.0.1:8001/sse",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

{
  "mcpServers": {
    "http-stream": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8002/mcp"
    }
  }
}

Architecture

Single container with three processes:

• Caddy (port 80) - Reverse proxy with optional HTTP Basic Auth
• Streamlit UI (localhost:8501) - Web interface for managing config
• MCPO Server (port 8000) - Proxy exposing MCP servers as OpenAPI
• Built-in watcher - Monitors /config directory, restarts MCPO on changes

┌─────────────────────────────────────┐
│      Container (mcpo-ui)            │
│                                     │
│  ┌─────────┐     ┌─────────────┐   │
│  │Caddy:80 │────>│Streamlit    │   │
│  │(+auth)  │     │localhost:8501│  │
│  └─────────┘     └──────┬──────┘   │
│                         │           │
│                         ▼           │
│                   config.json       │
│                         │           │
│                         ▼           │
│                  ┌──────────┐       │
│                  │MCPO:8000 │       │
│                  └──────────┘       │
│                  (auto-restarts)    │
└─────────────────────────────────────┘

Running Multiple Instances

# Copy project to new directory
cp -r . ../instance2
cd ../instance2

# Create .env with different ports and container name
cat > .env <<EOF
CONTAINER_NAME=mcpo-ui-2
UI_PORT=8080
MCPO_PORT=8001
MCPO_API_KEY=different-api-key
EOF

# Start second instance
docker-compose up -d

Environment variables (see .env.example):

• MCPO_API_KEY: API key for MCPO authentication (required)
• CONTAINER_NAME: Container name (default: mcpo-ui)
• UI_PORT: HTTP port for UI access (default: 80)
• MCPO_PORT: MCPO API port (default: 8000)
• MCPO_BASE_URL: Base URL for browser access (optional, for reverse proxy setups)
• UI_USERNAME: HTTP Basic Auth username (optional)
• UI_PASSWORD_HASH: HTTP Basic Auth password hash (optional)

Security

UI Authentication (Optional):

The UI includes Caddy reverse proxy with optional HTTP Basic Auth:

# 1. Generate password hash (automatically escaped for .env)
docker run --rm caddy caddy hash-password --plaintext yourpassword | sed 's/\$/\$\$/g'

# 2. Add to .env (use the escaped output from above)
UI_USERNAME=admin
UI_PASSWORD_HASH=$$2a$$14$$...

# 3. Restart container
docker-compose restart

Leave UI_USERNAME and UI_PASSWORD_HASH empty to disable authentication.

Alternative authentication options:

1. Coolify - Enable built-in HTTP Basic Auth in service settings (if using Coolify)
2. External Reverse Proxy - Use nginx/Traefik with auth
3. VPN/Firewall - Restrict network access to trusted IPs only

API Authentication: MCPO endpoints are protected by MCPO_API_KEY - always set this in production!

Troubleshooting

MCPO doesn't serve content at the server root. Access tools via:

• Docs: http://localhost:8000/<server-name>/docs
• Tool: http://localhost:8000/<server-name>/<tool-name> (POST)

# ✅ View docs
curl http://localhost:8000/time/docs

# ✅ Call tool
curl -X POST http://localhost:8000/time/get_current_time \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/New_York"}'

# Check watcher logs
docker logs <watcher-container-name>

# Manual restart
docker restart <mcpo-container-name>

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# View logs
docker-compose logs -f

# Rebuild
docker-compose up -d --build

Project Structure:

├── ui/                     # Streamlit UI source files
│   ├── app.py              # Main UI application
│   ├── config.example.json # Default config template
│   └── requirements.txt    # Python dependencies
├── Caddyfile               # Caddy reverse proxy config (HTTP Basic Auth)
├── entrypoint.sh           # Container entrypoint (manages all processes)
├── Dockerfile              # Single image with Caddy + UI + MCPO + watcher
├── docker-compose.yml      # Development setup
├── docker-compose.prod.yml # Production setup
└── config/                 # Volume for config.json (auto-created)

Production Deployment

Use the pre-built image from GitHub Container Registry:

# Using docker-compose.prod.yml
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Image: ghcr.io/tonghualabs/mcpo-ui:latest

Built with Streamlit and MCPO