MCP Workbench Cloud AI 工作台

MCP Workbench Cloud

A cloud-ready, self-hostable AI workbench. Chat with any model, give it tools through MCP, teach it skills, install Claude Code plugins, ground it in your own documents, and measure what it does.

Features · Screenshots · Quick start · Architecture · Security · Development · Roadmap

Why MCP Workbench Cloud

Most chat UIs stop at "pick a model, type a prompt". MCP Workbench Cloud is the bench around the model:

It is multi-user from the ground up: every record is scoped to its owner, secrets are encrypted, and uploaded files are private.

Features

Screenshots

Quick start

Requirements: Bun and PostgreSQL with pgvector (the dev compose file runs it for you).

git clone https://github.com/scorpiontaj/mcp-workbench.git
cd mcp-workbench
bun install

cp .env.example .env
# Required: ENCRYPTION_KEY and BETTER_AUTH_SECRET (openssl rand -base64 32), ADMIN_EMAILS (your email)

bun run docker:dev     # PostgreSQL + pgvector on localhost:5432
bun run db:migrate     # tables, the vector extension and built-in agents
bun run dev            # http://localhost:3000

1. Sign up. The emails in ADMIN_EMAILS become admins; after that, admins manage roles on /admin/users.
2. Add a provider on Providers: an API key, or the URL of a local Ollama / LM Studio.
3. Start a chat, or create a knowledge base with an embedding model such as text-embedding-3-small or nomic-embed-text.

Production: bun run docker:prod builds a multi-stage image that runs as non-root; then apply migrations as described in docker/README.md. The app container loads the repo-root .env, with DATABASE_URL and UPLOAD_DIR overridden to fit the stack. Provider keys in .env (OPENAI_API_KEY, ...) therefore reach the container: on a public deployment set SERVER_KEYS=admins or off, and ALLOW_PRIVATE_PROVIDER_URLS=false.

Scaling out: to run more than one app instance (or on serverless hosting), set REDIS_URL so rate limits are shared and survive restarts, and the S3_* variables so every instance reads and writes the same uploads. Without them, each instance keeps its own rate-limit counters and its own UPLOAD_DIR. Sessions already live in Postgres.

SaaS launch setup

The repository is ready to run as a multi-user service for individual accounts. Before inviting customers:

1. Set production BETTER_AUTH_URL, BETTER_AUTH_SECRET, ENCRYPTION_KEY, DATABASE_URL, and an email transport. Email verification is enforced when email is configured.
2. Set SERVER_KEYS=all only if customers should use the operator's model keys. Then set SERVER_KEYS_FREE_DAILY_LIMIT_USD and, if Stripe Pro is offered, STRIPE_PRO_DAILY_LIMIT_USD. SERVER_KEYS_DAILY_LIMIT_USD remains the operator's maximum per non-admin account across plans. Production defaults shared keys to admins when SERVER_KEYS is unset.
3. To offer Pro, create a recurring Stripe Price and configure STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_PRO, and STRIPE_PRO_DAILY_LIMIT_USD. Enable the Stripe customer portal and register https://<your-domain>/api/billing/webhook for customer.subscription.created, customer.subscription.updated, and customer.subscription.deleted. Billing stays unavailable until the complete configuration is valid.
4. Fill LEGAL_ENTITY_NAME, LEGAL_ENTITY_ADDRESS, LEGAL_EFFECTIVE_DATE, SUPPORT_EMAIL, PRIVACY_EMAIL, and LEGAL_TERMS_VERSION. The /terms and /privacy pages are starter templates, not reviewed legal advice; complete the jurisdiction and retention details and have counsel review them before launch.
5. Use private S3-compatible storage and Redis for multiple app instances. Configure, test, and document a backup retention period; deletion removes live records and files, while backup copies expire according to that operator policy.

New sign-ups must accept the Terms and Privacy Policy; the acceptance date and version are recorded. Settings provides account export and deletion. Exports include user files up to 100 MB and omit authentication tokens and provider credentials. Deleting an account cancels its Stripe subscriptions before removing the account and its files.

Architecture

MCP Workbench Cloud is a single Next.js 16 application: React pages for the UI and route handlers for the API, backed by PostgreSQL. Everything model-related goes through the Vercel AI SDK, so every provider gets the same streaming, tools, approvals and embeddings.

System overview

flowchart LR
  subgraph Browser["Browser"]
    UI["Next.js pages<br/>HeroUI v3 + Tailwind v4"]
    Py["Pyodide notebook<br/>(Web Worker)"]
  end

  subgraph Server["Next.js server"]
    Proxy["proxy.ts<br/>auth redirect + CSRF guard"]
    API["Route handlers /api/*<br/>withUser() → user-scoped"]
    Core["lib/<br/>models · mcp · skills · plugins<br/>knowledge · agents · uploads"]
  end

  subgraph Data["Storage"]
    PG[("PostgreSQL<br/>Drizzle ORM<br/>pgvector + tsvector")]
    Files[("storage/uploads<br/>private files")]
  end

  subgraph Outside["External services"]
    LLM["LLM providers<br/>OpenAI · Anthropic · Google<br/>Ollama · LM Studio · …"]
    MCP["Remote MCP servers<br/>HTTP / SSE"]
    GH["GitHub<br/>skills & plugins"]
    Reg["Official MCP Registry"]
  end

  UI -->|"fetch / SSE stream"| Proxy --> API --> Core
  Core --> PG
  Core --> Files
  Core -->|"AI SDK v7"| LLM
  Core -->|"ai-sdk/mcp client"| MCP
  Core --> GH
  Core --> Reg

One chat turn

The client sends only the new message; the server rebuilds the context, runs the model with every tool the chat and its agent allow, pauses for approvals when a server's policy asks for one, and saves the turn when the stream ends, even if the tab was closed.

sequenceDiagram
  autonumber
  participant B as Browser (useChat)
  participant R as /api/chat
  participant DB as PostgreSQL
  participant M as Model provider
  participant T as Tools (MCP · skills · knowledge)

  B->>R: new message (+ model, settings, picked skills and @ mentions)
  R->>DB: load chat history, agent, owned files
  R->>R: system prompt = agent + chat + skill list + knowledge note
  R->>M: streamText(messages, tools)
  loop up to the agent's step budget
    M-->>R: tool call
    alt server policy needs approval
      R-->>B: signed approval request
      B->>R: approve / deny
    end
    R->>T: execute
    T-->>R: result
    R->>M: continue with result
  end
  M-->>R: text stream
  R-->>B: UI message stream (text, tool cards, usage)
  R->>DB: save turn and token usage

What the model gets for a turn:

Knowledge pipeline

flowchart TB
  subgraph Ingest["Ingestion (background, after the request returns)"]
    S["Upload · web page · pasted text · dataset rows"] --> X["Extract text<br/>unpdf · HTML → text · CSV/Parquet → records"]
    X --> C["Chunk<br/>recursive splitter, size + overlap"]
    C --> E["embedMany()<br/>the base's embedding model"]
    E --> V[("KnowledgeChunk<br/>vector + generated tsvector")]
  end

  subgraph Search["Retrieval: search_knowledge tool"]
    Q["Question"] --> QE["embed() per embedding model"]
    Q --> KW["OR keyword query<br/>English stemming"]
    QE --> VS["cosine distance &lt;=&gt;"]
    KW --> FT["ts_rank_cd over GIN index"]
    VS --> F["Reciprocal rank fusion"]
    FT --> F
    F --> P["Top passages + sources → model cites them"]
  end

  V -.-> VS
  V -.-> FT

Each knowledge base fixes its embedding model, so bases built with different models can be searched together: the question is embedded once per model, and the ranked lists are fused.

Data model

erDiagram
  user ||--o{ Chat : owns
  user ||--o{ Agent : authors
  user ||--o{ McpServer : connects
  user ||--o{ Skill : has
  user ||--o{ Command : has
  user ||--o{ Plugin : installs
  user ||--o{ KnowledgeBase : owns
  user ||--o{ Dataset : uploads
  user ||--o{ ProviderConfig : configures

  Chat ||--o{ Message : contains
  Message ||--o{ Attachment : has
  Agent |o--o{ Chat : "linked to"

  Plugin ||--o{ Skill : adds
  Plugin ||--o{ Command : adds
  Plugin ||--o{ Agent : adds
  Plugin ||--o{ McpServer : adds

  KnowledgeBase ||--o{ KnowledgeDocument : holds
  KnowledgeDocument ||--o{ KnowledgeChunk : "split into"

  Message {
    jsonb parts "text, files, tool calls"
    int tokensIn
    int tokensOut
  }
  KnowledgeChunk {
    vector embedding
    tsvector tsv "generated"
  }
  McpServer {
    text headers "encrypted"
    text approval "never / readonly / always"
  }

Deleting a plugin cascades to everything it installed; deleting a knowledge base removes its documents and chunks. The schema lives in lib/schema.ts and the migrations in drizzle/.

Project layout

app/
  (pages)            chat, agents, compare, skills, plugins, knowledge, datasets, embeddings,
                     models, providers, tools (MCP inspector), registry, analytics, config, …
  api/               route handlers, one folder per resource; every handler is wrapped in withUser()
  uploads/[name]     serves a private upload to its owner
components/
  ui/                design-system primitives: HeroUI components behind a stable props API
  chat/ compare/ analytics/ datasets/ skills/ …   feature components
hooks/               SWR data hooks (useAgents, useKnowledgeBases, usePlugins, …)
lib/
  models.ts          provider → AI SDK language/embedding model, per-user keys
  mcp.ts             MCP clients, tool namespacing, approval policy
  skills.ts          progressive-disclosure skill tools
  composer.ts turn-context.ts              "/" and "@" picker parsing; per-message skills and mentions (ownership checks)
  bundles.ts plugins.ts github-source.ts   SKILL.md / plugin parsing and GitHub fetching
  knowledge.ts rag-text.ts                 ingestion, chunking, hybrid search
  tabular.ts datasets.ts                   CSV/Parquet parsing and column profiling
  uploads.ts upload-access.ts              private file storage and access checks
  schema.ts db.ts    Drizzle schema and client
scripts/             mock-llm.ts, mock-mcp.ts, migrate-uploads.ts
drizzle/             SQL migrations
docker/              Dockerfile and compose files

Design decisions

• One AI layer. Every provider goes through the AI SDK (getModel / getEmbeddingModel), so chat, tools, comparison and embeddings behave the same everywhere.
• The server owns the conversation. Clients send the new message only; history, tools and approvals are rebuilt on the server, so a modified client can't rewrite history or forge an approval.
• Pure parsers, thin routes. Skill/plugin parsing, chunking, CSV and MCP-config parsing, rank fusion and PATCH schemas are pure functions with unit tests; routes validate input with zod and stay small.
• Postgres does the retrieval. pgvector and full-text search run side by side in one database, so there's no separate vector store to run or keep in sync.
• Design system behind stable props. components/ui keeps one component API while rendering HeroUI v3, so the whole app moved to HeroUI at once and can keep evolving.

Local stdio MCP servers

The hosted app can't start processes on your machine, so local servers (the npx … and uvx … kind) run through a small bridge you start yourself. It launches the server once per session and exposes it as a Streamable HTTP endpoint protected by OAuth:

bun scripts/mcp-bridge.ts --port 8808 -- npx -y @modelcontextprotocol/server-filesystem ~/notes

It prints a URL and a pairing code. In the MCP Inspector, add http://127.0.0.1:8808/mcp with authentication OAuth sign-in and sign in: the bridge registers the workbench, opens its approval page, and you approve with the pairing code from its terminal. Tokens refresh on their own; restarting the bridge signs clients out and prints a new code, and after 10 wrong codes it stops approving until restarted. Clients without OAuth can send the Authorization: Bearer <token> header the bridge also prints.

A self-hosted workbench reaches it directly (set ALLOW_PRIVATE_PROVIDER_URLS=true). For the hosted app, expose it with a tunnel such as cloudflared tunnel --url http://127.0.0.1:8808, add the tunnel's https URL instead, and start the bridge with --public-url https://<tunnel-host> so its OAuth metadata names that address.

Security model

Development

bun run dev          # Next.js dev server
bun run check        # typecheck + lint + unit tests (CI also runs a production build)
bun run db:generate  # create a migration after editing lib/schema.ts
bun run db:migrate   # apply migrations

Calling the API from scripts: create a personal key under Settings → API keys (it is shown once) and send it as a bearer token. Keys work on every user API route except admin routes and key management:

curl -H "Authorization: Bearer mwb_…" http://localhost:3000/api/chats

Mock services for working without API keys:

CI (.github/workflows/ci.yml) installs with a frozen lockfile, then runs typecheck, lint, tests and a production build.

Contributing

1. Fork the repository and create a branch.
2. Run bun run check before pushing.
3. Open a pull request describing what changed and how you tested it.

License

MIT, see LICENSE.

Made by Tajeddine Bourhim