Open Design MCP Server

Overview

Open Design MCP Server exposes the Open Design daemon's REST API as 15 MCP tools over the StreamableHttp transport, enabling any MCP-compatible AI client (Claude App, Claude Code, n8n, etc.) to create, iterate, and manage AI-generated design projects.

The package includes a full-featured Admin GUI (React 19 SPA) for monitoring, tool management, token rotation, and live log viewing — all secured with JWT authentication, CORS allowlists, and security headers.

Why This Package?

Features

Core Capabilities

• 15 MCP Tools — System info, project CRUD, file access, AI chat (SSE streaming), content discovery

• StreamableHttp Transport — Network-accessible MCP via Supergateway (stdio → HTTP bridge)

• SSE Response Parser — Handles long-running AI agent operations with real-time text streaming

• Configurable Timeouts — 60s for reads, 300s for AI chat operations

Admin GUI

• Dashboard — Real-time health monitoring (daemon, MCP server, proxy status)

• Tool Manager — Enable/disable individual MCP tools without restarting

• Token Manager — Generate, rotate, and manage MCP authentication tokens

• Log Viewer — Live-streaming server logs with severity filtering

• Settings — Connection configuration with SSRF-protected connectivity testing

Security

• JWT Authentication — HS256 tokens with configurable expiry (default 24h)

• CORS Allowlist — Explicit origin allowlist (no wildcards)

• Security Headers — HSTS, X-Frame-Options: DENY, X-Content-Type-Options, Referrer-Policy

• SSRF Protection — Block metadata endpoints (169.254.169.254), loopback, link-local addresses

• Request Size Limit — 1 MB body limit to prevent abuse

• Encrypted MCP Proxy — Token-based URL path for MCP endpoint access

• Secure Cookies — HttpOnly, Secure, SameSite=Strict

Architecture

graph TB
    subgraph External["External AI Clients"]
        Claude["Claude App / Claude Code"]
        N8N["n8n / Custom MCP Client"]
    end

    subgraph CF["Cloudflare Tunnel"]
        CFT["*.woowtech.io"]
    end

    subgraph Pod["K8s Pod: od-mcp"]
        subgraph AdminGUI["Admin GUI — FastAPI :8080"]
            Auth["JWT Auth Middleware"]
            SecHeaders["Security Headers"]
            Proxy["/private_{token}/mcp → Reverse Proxy"]
            SPA["React 19 SPA"]
            API["REST API /api/*"]
        end

        subgraph SG["Supergateway — Node.js :8000"]
            STDIO["stdio → StreamableHttp Bridge"]
        end

        subgraph MCP["MCP Server — FastMCP"]
            Tools["15 MCP Tools"]
        end
    end

    subgraph OD["Open Design Daemon"]
        ODAPI["REST API :7457"]
    end

    Claude --> CFT
    N8N --> CFT
    CFT --> Auth
    Auth --> SecHeaders
    SecHeaders --> Proxy
    Proxy --> STDIO
    STDIO --> Tools
    Tools --> ODAPI
    CFT --> SPA
    SPA --> API

Three-Component Architecture

Data Flow

AI Client → Cloudflare Tunnel → Admin GUI (:8080)
                                    ├── /private_{token}/mcp → Supergateway (:8000) → MCP Server (stdio) → OD Daemon (:7457)
                                    └── /api/* → REST API (settings, tools, tokens, logs)

MCP Tools (15)

Category A: System Tools (4)

Category B: Project Tools (5)

Category C: File Tools (2)

Category D: AI Chat Tools (2)

Category E: Content Tools (2)

Admin GUI

Login

Secure JWT-based authentication with admin password.

Dashboard

Real-time health monitoring — OD Daemon status, MCP Server status, Proxy status, daemon version, and namespace info.

Tool Manager

Enable or disable individual MCP tools. View tool categories, parameters, and descriptions.

Token Manager

Generate and rotate MCP authentication tokens. View token history and connection URLs.

Log Viewer

Live-streaming server logs with auto-scroll and severity filtering.

Settings

Connection configuration, MCP server process management, and SSRF-protected connectivity testing.

Quick Start

Docker

# Build
docker build -t od-mcp-server:latest .

# Run
docker run -d \
  -p 8080:8080 \
  -p 8000:8000 \
  -e OD_API_BASE=http://your-od-daemon:7457 \
  -e JWT_SECRET=your-secret-key \
  -v od-mcp-data:/data \
  od-mcp-server:latest

Kubernetes (K3s)

# Apply manifests
kubectl apply -f k8s-manifests/

# Verify
kubectl get pods -n open-design
kubectl logs -n open-design deployment/od-mcp -c admin-gui

MCP Client Configuration

Connect any MCP client using the StreamableHttp endpoint:

{
  "mcpServers": {
    "open-design": {
      "url": "https://your-domain.com/private_{YOUR_TOKEN}/mcp",
      "transport": "streamable-http"
    }
  }
}

Tech Stack

Backend (Python)

Frontend (JavaScript)

Infrastructure

Project Structure

.
├── od_mcp_server.py          # MCP server — 15 tools (FastMCP, stdio)
├── od_mcp_admin/             # Admin GUI app (FastAPI entry point)
│   └── routers/
│       └── config.py         # OD-specific connection config router
├── mcp_admin_core/           # Shared admin framework
│   ├── app.py                # FastAPI app factory + security middleware
│   ├── auth/
│   │   └── middleware.py     # JWT auth middleware + login router
│   ├── config.py             # JSON config store
│   ├── process.py            # MCP server process manager
│   ├── proxy.py              # MCP reverse proxy
│   └── routers/
│       └── settings.py       # Full config management API
├── frontend/                 # React 19 SPA (Vite + Tailwind CSS 4)
│   ├── src/
│   │   ├── pages/            # Dashboard, Tools, Tokens, Logs, Settings
│   │   └── components/       # Shared UI components
│   └── package.json
├── k8s-manifests/            # Kubernetes deployment manifests
├── Dockerfile                # Multi-stage build (Node 22 + Python 3.12)
├── entrypoint.sh             # Container startup script
└── pyproject.toml            # Python project configuration

Security

• Authentication: JWT (HS256) with configurable expiry, secure cookie storage

• Transport: All traffic encrypted via Cloudflare Tunnel (TLS 1.3)

• CORS: Explicit origin allowlist — no wildcard *

• Headers: HSTS, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy

• SSRF Protection: Blocks requests to cloud metadata endpoints, loopback, and link-local addresses

• Request Limits: 1 MB body size limit

• Token Security: MCP tokens masked in API responses, rotation with history tracking

• API Surface: Swagger/OpenAPI docs disabled in production

License

MIT License. See LICENSE for details.