liz-whiteboard-mcp — MCP Server for ER Diagrams & Database Schema Editing (Go, OAuth 2.1)

A Model Context Protocol (MCP) server that lets AI agents — Claude, Cursor, VS Code, Claude Code — read and edit entity-relationship (ER) diagrams and SQL database schemas in liz-whiteboard. Written in Go, it serves the Streamable HTTP transport and authenticates clients with OAuth 2.1 (PKCE + JWKS).

This is the AI integration layer for liz-whiteboard, the open-source collaborative ER diagram and database schema designer. Connect any MCP-compatible AI client and design databases conversationally — "add a users table with a one-to-many relationship to orders" — and watch the changes appear live on the whiteboard. Compiles to a single self-contained binary (pure Go, no cgo, no Node/Bun runtime).

Table of contents

• What it does

• The 17 MCP tools

• How it works

• Quick start (local, dev token)

• Deploy with Docker (single domain)

• Connect an MCP client (OAuth)

• Configuration

• Project layout

• Testing

• License

Related MCP server: SQLite Cloud MCP Server

What it does

Exposes the liz-whiteboard ER diagram as MCP tools so an LLM agent can:

• Discover — list the user's projects and whiteboards.

• Read — load a whiteboard's full diagram (tables, columns, relationships, positions) or a compact text schema summary.

• Write — create / update / delete tables, columns, and relationships; reorder columns; bulk-move tables.

Reads go straight to the app's SQLite database; writes are sent to the live collaboration server over Socket.IO and broadcast to every connected user in real time. Every request is scoped to the authenticated user (project-membership checks).

The 17 MCP tools

How it works

AI client (Claude / Cursor)
   │  OAuth 2.1 (PKCE) → access token (RS256 JWT)
   ▼
liz-whiteboard-mcp  ── OAuth 2.0 Resource Server (RFC 9728 + RFC 8707) ──
   │  • validates the JWT via the AS's JWKS (iss / aud / exp / signature)
   │  • resolves identity per request (sub = User.id), checks project access
   ├── reads  → SQLite (data/app.db)
   └── writes → Socket.IO collaboration server
                (authenticated with a separate collab-audience JWT —
                 the client's token is never passed through)

• Transport: MCP Streamable HTTP (POST /mcp).

• AuthN/Z: OAuth 2.1 Resource Server. Serves Protected Resource Metadata at /.well-known/oauth-protected-resource, returns 401 + WWW-Authenticate for unauthenticated requests, and validates audience-bound RS256 tokens issued by the liz-whiteboard Authorization Server.

• No token passthrough: writes use a distinct collaboration token (avoids the OAuth "confused deputy" problem).

Quick start (local, dev token)

Requirements: Go 1.25+.

make build        # → ./liz-whiteboard-mcp   (or: go build ./cmd/mcp/)

# Run with the DEV-ONLY stub verifier (skips the full OAuth flow for local testing).
# NEVER set MCP_DEV_AUTH in production.
DATABASE_URL="file:/absolute/path/to/liz-whiteboard/data/app.db" \
MCP_DEV_AUTH=stub \
MCP_DEV_STUB_TOKEN="dev-token" \
MCP_DEV_USER_ID="<a-real-user-uuid>" \
LIZ_SOCKET_URL="ws://localhost:3010" \
./liz-whiteboard-mcp
# → serves http://127.0.0.1:3011/mcp

Then call it with Authorization: Bearer dev-token. Without MCP_DEV_AUTH=stub, the server runs in production mode and requires real OAuth (see below).

Deploy with Docker (single domain)

The repo ships a Docker Compose stack that runs the app + Authorization Server + this MCP server behind one reverse proxy (Caddy) — so clients use a single origin, no separate ports:

http://localhost:8080/        → liz-whiteboard app + OAuth (/authorize, /token, JWKS)
http://localhost:8080/mcp     → this MCP server

bash deploy/run.sh            # provisions a persistent signing key + secret, then docker compose up

See docker-compose.yml and deploy/Caddyfile. The Go server itself builds to a tiny distroless image via the Dockerfile.

Connect an MCP client (OAuth)

Point an MCP client (Claude Desktop, Claude Code, Cursor, VS Code) at the server URL (e.g. https://your-domain/mcp). The client performs the standard MCP OAuth flow automatically:

1. Calls /mcp, gets 401 + the Protected Resource Metadata URL.

2. Discovers the Authorization Server, runs the browser authorize → consent → token flow (PKCE).

3. Retries /mcp with the bearer token.

No API keys or copied cookies required.

Configuration

Project layout

cmd/mcp/main.go        # entrypoint: HTTP transport, OAuth wiring, tool registration
internal/auth          # OAuth Resource Server: JWKS verifier, per-request identity, project scoping
internal/db            # SQLite connection (database/sql + modernc.org/sqlite, no cgo)
internal/data          # raw-SQL read layer
internal/socket        # Socket.IO write path + collab-token client
internal/tools         # the 17 MCP tool handlers
internal/errors        # error taxonomy + token redaction
internal/{positioning,schema,summary}  # helpers

Testing

make test              # unit tests (no database required)

# Integration tests against a real SQLite database:
make test-integration DATABASE_URL=file:/abs/path/to/liz-whiteboard/data/app.db

License

MIT © LizardLiang

Keywords: Model Context Protocol server, MCP server Go, MCP server example, OAuth 2.1 resource server, JWKS, PKCE, RFC 9728, RFC 8707, AI database design, ER diagram MCP, SQL schema MCP tools, Claude MCP server, Cursor MCP, Claude Code, Socket.IO, SQLite, modernc, self-hosted MCP, streamable HTTP MCP.