ClientDesk MCP

A Claude connector for professional-services firms. Staff ask Claude about clients and documents in plain English. ClientDesk answers through MCP tools with cited sources, files incoming documents only when it is sure, enforces who may see which client, and logs every call. A dashboard shows the audit log, the review queue and a measured accuracy report.

All data is fictional: the demo firm is Northbridge Advisory with 3 staff, 12 clients and 13 documents.

What it proves

Related MCP server: clio-mcp

Tools

Read tools are annotated readOnlyHint: true; write tools readOnlyHint: false with destructiveHint set, so Claude asks before running them.

Accuracy

The latest report is in eval/report.md and on the dashboard's Accuracy page. The committed report uses the offline rules baseline (free, deterministic, run in CI on every push):

The baseline can't read prose layouts or noisy scans, so those go to review: that is the safe failure, not a wrong filing. The Claude extractor (Haiku 5.5, escalating to Opus 5.5 when unsure) is measured with npm run eval:claude (about $0.10–0.30 a run). The report lists every case, every miss and what was changed.

Run it locally

Requires Node 22+. No database or keys needed: local development uses PGlite (Postgres in WASM, with pgvector), the offline extractor and local embeddings.

npm install && npm run dashboard:install
cp .env.example .env
npm run dashboard:build
npm run dev          # MCP at http://localhost:3000/mcp, dashboard at http://localhost:3000/dashboard/
npm run check        # typecheck + lint + tests
npm run eval         # accuracy report → eval/report.md, eval/report.json

Add ANTHROPIC_API_KEY (extraction with Claude) and VOYAGE_API_KEY (embeddings) to .env to use the real models; everything else stays the same. npm run seed -- --reset reloads the demo firm.

For dashboard development with hot reload: npm run dev in one terminal, npm run dashboard:dev in another (Vite on :5173, proxied to the server).

Use it from Claude Code (stdio)

claude mcp add clientdesk --env CLIENTDESK_USER=tom@northbridge.example -- npx tsx src/stdio.ts

Then ask: "What's still missing for Acme Ltd's 2026 return?", "File the new invoice in the inbox", or "Show me Lakeside Dental Group" (Tom isn't assigned to it, so it's refused and logged).

Use it from Claude (web or Desktop) as a custom connector

Claude connects from Anthropic's cloud, so the server needs a public HTTPS URL and real sign-in:

1. Create a WorkOS AuthKit application with dynamic client registration on, redirect URI https://claude.ai/api/mcp/auth_callback, and a JWT template that adds email to access tokens.

2. ngrok http 3000, then run with AUTH_MODE=oauth PUBLIC_URL=https://<ngrok-host> OAUTH_ISSUER=https://<subdomain>.authkit.app.

3. In Claude: Customize → Connectors → Add custom connector, URL https://<ngrok-host>/mcp, and sign in.

docs/PLAN.md has the full checklist and the gotchas.

Deploy

render.yaml (Render blueprint) + Dockerfile build the server and dashboard into one image. Production uses Neon (Postgres + pgvector) via DATABASE_URL and Cloudflare R2 for files (STORAGE=r2). Production refuses to start without OAuth, an https PUBLIC_URL, SESSION_SECRET and LINK_SECRET.

Architecture

Claude (web / Desktop / Code)                 Dashboard (React + Vite, /dashboard)
        │  MCP: Streamable HTTP or stdio              │  JSON API (/api), session cookie or dev header
        ▼                                             ▼
src/http.ts ── OAuth bearer check → resolveActor()   src/web/ ── session, sign-in, API routes
        ▼                                             │
src/mcp/server.ts ── one McpServer per request        │
        ▼                                             │
src/mcp/tools/* ── runTool() → audit row              │
        ▼                                             ▼
src/domain/* ── access, clients, documents, intake, matching, search, audit (plain functions over Db)
        ▼                       ▼                         ▼
src/db/ (PGlite / Neon)   src/ai/ (Claude, Voyage,   src/storage/ (local / R2)
                          offline fallbacks)

Built with Claude Code

• CLAUDE.md: commands, architecture and the rules that must not be broken.

• Skills in .claude/skills: add-mcp-tool, add-migration, security-review.

• Hooks in .claude/settings.json: Prettier after every edit; a turn can't finish while typecheck or lint fails.

Docs

• docs/PLAN.md: plan, decisions and status

• docs/DEMO-SCRIPT.md: the 3-minute video, shot by shot

• docs/CASE-STUDY.md: the write-up for clients

• eval/report.md: the latest accuracy report

License

MIT