Liz Whiteboard

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 19 MCP tools
• How it works
• How to install & run
• Quick start (local, dev token)
• Deploy with Docker (single domain)
• Connect an MCP client (OAuth)
• Configuration
• Project layout
• Testing
• License

---

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 19 MCP tools

Group	Tools
Discovery	list_projects, list_whiteboards
Read	get_board, get_schema_summary, get_table_ddl
Tables	create_table, update_table, delete_table
Columns	create_column, update_column, delete_column, reorder_columns
Relationships	create_relationship, update_relationship, delete_relationship
Positions	bulk_update_positions
Batch	batch_schema_update
Static	list_data_types (25), list_cardinalities (17)

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).

How to install & run

Pick one of three ways to get the binary, then point an MCP client at it.

1. Install the binary

Option A — go install (needs Go 1.25+; produces a binary named mcp):

go install github.com/LizardLiang/liz-whiteboard-mcp/cmd/mcp@latest
# → $(go env GOPATH)/bin/mcp   (add that dir to your PATH)

Option B — build from source:

git clone https://github.com/LizardLiang/liz-whiteboard-mcp
cd liz-whiteboard-mcp
make build        # → ./liz-whiteboard-mcp

Option C — Docker (runs the whole stack; skip to Deploy with Docker).

2. Run it

Set the environment (see Configuration) and start the server. It listens on 127.0.0.1:3011 by default and serves the MCP endpoint at /mcp:

DATABASE_URL="file:/absolute/path/to/liz-whiteboard/data/app.db" \
OAUTH_ISSUER="https://your-domain" \
MCP_RESOURCE_URI="https://your-domain/mcp" \
LIZ_SOCKET_URL="ws://localhost:3010" \
MCP_CLIENT_SECRET="<shared-with-the-app>" \
COLLAB_TOKEN_URL="https://your-domain/api/collab-token" \
./liz-whiteboard-mcp

For local testing without a full OAuth setup, use the dev-token path in Quick start instead.

3. Connect your AI client

Register the running server with any MCP client. For Claude Code:

claude mcp add --transport http liz-whiteboard https://your-domain/mcp

On first use the client runs the browser OAuth flow automatically (see Connect an MCP client) — no API keys to copy. For Claude Desktop / Cursor / VS Code, add the same URL in the client's MCP server settings.

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

Variable	Description
DATABASE_URL	SQLite file — the same data/app.db the app uses (e.g. file:/abs/path/data/app.db).
MCP_LISTEN_ADDR	Listen address (default 127.0.0.1:3011).
OAUTH_ISSUER	Public issuer URL of the Authorization Server; validated in the token iss claim.
MCP_RESOURCE_URI	Canonical public URI of this server (e.g. https://your-domain/mcp); the expected token aud.
OAUTH_JWKS_URL	Optional — fetch JWKS from an internal address while OAUTH_ISSUER stays public (reverse-proxy / split-horizon). Defaults to {issuer}/.well-known/jwks.json.
LIZ_SOCKET_URL	Collaboration Socket.IO server URL (write path), e.g. ws://localhost:3010.
MCP_CLIENT_ID / MCP_CLIENT_SECRET	Confidential-client credentials used to mint collaboration tokens from the AS (MCP_CLIENT_ID defaults to mcp-server).
COLLAB_TOKEN_URL / COLLAB_RESOURCE_URI	AS collab-token endpoint and the collaboration token audience.
MCP_DEV_AUTH, MCP_DEV_STUB_TOKEN, MCP_DEV_USER_ID	Dev only — enable the stub verifier. Never set in production.

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 19 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.