🖥️ MCP Workstation

One MCP endpoint. Every MCP server. Your own multi-user platform.

MCP Workstation is a single MCP server that acts as an aggregator: your AI client connects to it once and gets every tool from every MCP server you've registered — plus a dense set of built-in tools — behind one connection.

Run it in platform mode (set BETTER_AUTH_SECRET) and it becomes a full product:

• Sign-in with Google or GitHub (Better Auth) at a built-in dashboard (/)

• Per-user MCP servers — each user registers their own stdio/HTTP MCP servers, with secrets stored encrypted (AES-256-GCM), and toggles them on/off

• API tokens per user; every /mcp request must carry Authorization: Bearer <token>

• Per-user catalogs — tool lists are built per request from that user's enabled servers and module prefs. Users only ever see their own servers.

• Categorized modules & tools — everything ships on by default, grouped by category (Development, Data, Finance & Crypto, …), with per-tool toggles: turn off a whole module or a single tool (e.g. keep crypto_price but hide crypto_trending).

• A Skills Hub — reusable agent instruction sets (debugging, code review, security audits, …) shipped alongside the MCP tools, browsable in the dashboard and loadable by any connected client via skills_list / skills_get. One hub, MCP + skills together.

It speaks the 2026-07-28 MCP specification (the newest release): a stateless protocol core. There is no initialize handshake, no Mcp-Session-Id, no connection state — every request is self-contained and independently authenticated, so the server scales behind a plain round-robin load balancer. Tools are namespaced (github_create_issue, mybox_read_file, …) so nothing collides and routing is automatic.

┌──────────────┐   Bearer token + stateless request   ┌─────────────────────────────────┐
│  Claude /    │ ───────────────────────────────────▶ │         MCP Workstation        │
│  Cursor /    │  http://localhost:3125/mcp           │  ┌───────────────────────────┐  │
│  VS Code     │ ◀─────────────────────────────────── │  │ Built-in modules (shared) │  │
└──────────────┘                                     │  │  time uuid memory github… │  │
┌──────────────┐                                     │  └───────────────────────────┘  │
│  Browser     │  /  (dashboard)                     │  ┌───────────────────────────┐  │
│  Google /    │ ──────────────────────────────────▶ │  │ Per-user proxy engine    │  │
│  GitHub      │  /api/auth/*, /api/*                │  │  ▶ user's stdio servers   │  │
└──────────────┘                                     │  │  ▶ user's HTTP servers    │  │
                                                     │  └───────────────────────────┘  │
                                                     └─────────────────────────────────┘

Quick start

Requires Node.js ≥ 22.5 (for the built-in node:sqlite).

1. Run with platform mode (recommended):

npm install
npm run build
cp .env.example .env        # then set BETTER_AUTH_SECRET + OAuth keys (see below)
npm start

2. Or run single-user, no auth (everything is open):

npm start                   # platform mode stays off without BETTER_AUTH_SECRET

You'll see a startup report listing active modules, connected upstream servers, and whether platform mode is on:

[mcp-workstation]   ✔ time: 2 tools
[mcp-workstation]   ✖ github: GITHUB_TOKEN not set
[mcp-workstation] 22 tools available
[mcp-workstation] platform mode: ON (multi-user auth)
[mcp-workstation] dashboard: http://localhost:3125/

Related MCP server: MCPGate

Platform mode — turning it on

Add to .env:

BETTER_AUTH_SECRET=$(openssl rand -base64 32)   # REQUIRED — turns platform mode on

# Google OAuth (redirect URI: {BETTER_AUTH_URL}/api/auth/callback/google)
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# GitHub OAuth (callback URL: {BETTER_AUTH_URL}/api/auth/callback/github)
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Then open http://localhost:3125/ and sign in with Google or GitHub. Email/password sign-in is on by default for development (ALLOW_EMAIL_AUTH=false to disable).

From the dashboard you can:

• Add MCP servers — pick stdio (a local command) or http (a remote endpoint), name it (tools appear as name_*), and set env vars / headers. Secrets are encrypted at rest and never returned by the API.

• Toggle servers on/off — disabled servers stop appearing in your endpoint instantly.

• Mint API tokens — name a token (e.g. "Claude Code"), copy it once, revoke anytime.

• Toggle modules & individual tools — everything is on by default; drill into any module and switch off single tools, or hide whole categories you don't use.

• Browse the Skills Hub — enable/disable skills, read their full instructions, and let your clients pull them over MCP.

Connect your AI client

First create an API token in the dashboard. Then point your client at the endpoint with the token as a Bearer header:

The endpoint serves the 2026-07-28 stateless protocol, falls back to serving 2025-era streamable-HTTP requests automatically, and still bridges the deprecated legacy HTTP+SSE transport for older clients (in platform mode its message POSTs are authenticated too). Requests without a valid token get a proper 401 + WWW-Authenticate challenge.

Local apps can also use stdio (single-user mode):

npm run stdio

What's new — 2026-07-28 features wired in

• Stateless core — no handshake, no sessions. Each request carries its protocol version, client identity, and capabilities in a _meta envelope. The old session-recovery/session-reaping code is gone entirely; the server is just a handler.

• server/discover — clients can probe capabilities up front (optional).

• Cacheable list results — tools/list and server/discover return ttlMs + cacheScope hints (tool catalogs only change on reload).

• Header-based routing — requests carry Mcp-Method / Mcp-Name headers, so gateways, rate limiters, and WAFs can route and meter without parsing JSON bodies (missing headers are rejected with a spec-compliant error).

• resultType: "complete" results with io.modelcontextprotocol/serverInfo in _meta.

• Built on SDK v2 (@modelcontextprotocol/server + @modelcontextprotocol/client), web-standards based, with the client auto-negotiating protocol era against upstreams.

MCP Registry integration

• Discover & import: the dashboard Directory searches the official MCP Registry (registry.modelcontextprotocol.io) live — one click adds any remote server to your account as a namespaced upstream (/api/registry is a read-only, session-gated proxy; no keys leave the server side).

• Publish our hub: registry/server.json is a valid entry (io.github.anshace/mcp-workstation, validated offline against the vendored official schema via npm run validate:registry). To list it publicly: point the remote url at your deployed instance, claim the namespace via GitHub, and submit with the official mcp-publisher CLI.

Built-in tools (no API keys needed for the core set)

In platform mode the key-gated modules (github, jira, search, notion, slack) are per-user: each account can store its own credentials on the dashboard's Credentials page (API: /api/secrets, encrypted at rest, never displayed back) and those shadow the server's process env — so one user's gh_* calls never run with another's token.

Lite catalog — search-first, token-frugal (on by default for new users)

Every agent pays for tools/list in its context window — a full workstation catalog is 60+ tools ≈ tens of thousands of tokens. Lite mode lists only five Tier-0 tools and keeps everything else fully reachable behind them:

Toggle per user on the dashboard (Modules & Tools → Lite catalog) or via PUT /api/prefs {"liteCatalog":false} for clients that want the full static list. Retrieval reuses our tool-index work (src/toolsearch.ts, unit-tested against a 20-probe intent set at ≥90% accuracy).

Oversized tool results (default >200KB, MAX_RESULT_BYTES) are spilled to a file in the workspace and replaced by a preview + fs_read pointer, so one chatty upstream never floods the agent's context. | skills | skills_list, skills_get — pull your enabled skills' instructions over MCP | always |

GitHub and Jira both support enterprise/self-hosted instances via GITHUB_API_URL and JIRA_BASE_URL. Jira accepts an API token (Basic auth with JIRA_EMAIL) or a PAT. | postgres | pg_list_tables/describe_table/query | DATABASE_URL | | notion | notion_search/get_page/list_block_children/create_page/append_blocks | NOTION_TOKEN | | slack | slack_post_message/list_channels/channel_history/list_users | SLACK_BOT_TOKEN | | workstation | workstation_status, workstation_reload | always |

Copy .env.example to .env, fill in the keys you have, and restart. Missing keys simply disable that module — everything else keeps working.

🧠 Knowledge base — full-text + vector search (zero config)

The knowledge module gives your AI a searchable memory, out of the box:

• Full-text search — SQLite FTS5 with BM25 ranking (knowledge_fts_search)

• Semantic vector search — local embeddings (all-MiniLM-L6-v2, 384-dim), downloaded once and cached; runs fully offline afterwards (knowledge_vector_search)

• Hybrid search — FTS + vector merged and ranked (knowledge_search)

• Auto-fallback — if the embedding model can't load, a TF-IDF vectorizer takes over, so search always works

• Workspace indexing — knowledge_index_workspace crawls the sandboxed filesystem roots and indexes text/code files in chunks

# add documents, then search
knowledge_index        { "text": "...", "title": "...", "source": "..." }
knowledge_search       { "query": "feline companions that purr" }   # semantic
knowledge_fts_search   { "query": "javascript server" }              # exact/BM25

The embedding model downloads on first vector-search use (one-time, ~23 MB), stored in the local HuggingFace cache. No API keys required.

💡 Skills Hub — instructions your agents can follow

The workstation ships a library of skills: markdown playbooks for recurring work (debugging, code-review, git-workflow, sql-querying, web-research, documentation, deployment-checklist, security-audit — each with a description, category and version). They sit next to the MCP tools in one hub:

• Everything is on by default — no setup.

• The dashboard has a dedicated Skills page: browse by category, read any skill's full instructions in a preview, and toggle skills on/off per user.

• Connected clients pull them over MCP: skills_list (names, descriptions, categories) then skills_get { "name": "debugging" } for the full content.

• Skills live in skills/*.md — add one with the same frontmatter (name, description, category, version) and rebuild.

Adding your own MCP servers (the aggregator part)

Copy config/servers.example.json to config/servers.json and list the servers you want aggregated. The workstation connects to each at startup (via the v2 client, which auto-negotiates with both modern and legacy upstream servers) and merges their tools into its own list, prefixed with the server's key.

{
  "servers": [
    {
      "key": "myfiles",                       // → tools appear as myfiles_*
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/path/to/folder"],
      "env": { "SOME_TOKEN": "..." }          // optional extra env for the child process
    },
    {
      "key": "remote",
      "type": "http",                         // remote Streamable HTTP / SSE servers
      "url": "https://your-mcp-server.example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  ]
}

• enabled: false (or a bad entry) skips the server; a server that fails to start is reported in workstation_status instead of crashing the workstation.

• After editing servers.json, call the workstation_reload tool — because every HTTP request builds a fresh tool catalog from the live registry, the new tools appear on the very next tools/list.

Operations

• workstation_status — which modules are active (and why others aren't), which upstream servers are connected, total tool count, protocol version.

• workstation_reload — re-reads servers.json, reconnects upstreams, refreshes the tool list.

• Endpoint path and port are configurable: MCP_PATH (default /mcp), PORT (default 3125).

Security notes

• Every /mcp request is authenticated in platform mode. No token, no tools. Tokens are stored as SHA-256 hashes, never plaintext; per-user server secrets (env vars, headers) are encrypted with AES-256-GCM using BETTER_AUTH_SECRET and never returned by the API.

• Multi-tenant isolation. Each request builds the tool catalog from that user's enabled servers and prefs — a user can never see or call another user's servers.

• Filesystem is sandboxed. fs_* tools refuse paths outside FILESYSTEM_ROOTS (default ./data/workspace).

• Databases are read-only by default. pg_query and sqlite_query block write statements unless you explicitly set PG_ALLOW_WRITE=true / SQLITE_ALLOW_WRITE=true.

• fetch_url can be restricted to specific domains with allowed_domains.

• Every key-gated module is off unless you set the key. Nothing phones home.

• In single-user mode (no BETTER_AUTH_SECRET) there is no auth — bind to localhost or put a reverse proxy in front. Sessions use secure cookies automatically when the public URL is HTTPS.

Development

npm run check                 # typecheck + web typecheck + dead-code gate + unit tests
npm run typecheck         # fast type check (backend)
npm run typecheck:web     # type check (React dashboard)
npm run test:unit         # fast unit tests for core modules (no build needed)
npm test                  # builds + unit tests + the core end-to-end smoke test
npm run test:platform     # platform mode: signup → tokens → per-user /mcp → isolation
npm run test:integrations # GitHub + Jira modules against a local mock API (no real credentials)
npm run dev               # run the backend from source (serves the built dashboard at /)
npm run dev:web           # Vite dev server for the dashboard (proxies /api + /mcp to the backend)
npm run build:web         # rebuild the dashboard into public/ (served by the backend)

See CONTRIBUTING.md (how to add a module) and docs/ARCHITECTURE.md (how the pieces fit together).

Project layout

src/
  index.ts            entry point: boots workstation + platform (auth, DB, dashboard)
  server.ts           per-request McpServer built for the authenticated user,
                      shared registry + per-user upstream aggregators
  http.ts             node:http front-end: /api/auth/*, /api/*, static UI, /mcp
                      (Bearer-gated in platform mode, legacy SSE bridge kept)
  config.ts           .env + config/servers.json loading
  registry.ts         mutable tool registry + module registration
  platform/
    auth.ts           Better Auth instance (Google + GitHub, cookies)
    db.ts             SQLite: auth tables (auto-migrated) + servers/tokens/prefs
    tokens.ts         API-token mint/verify + the /mcp Bearer verifier
    api.ts            dashboard REST API (servers CRUD, tokens, prefs, skills,
                      secrets, registry import proxy)
    oauth.ts          OAuth 2.1 authorization server for /mcp (RFC 9728/7591:
                      DCR, consent, PKCE S256 → mcw_ bearer)
    serverConfig.ts   encrypted server-row codec (shared by core + REST)
  toolsearch.ts       ephemeral BM25 tool index + module synonym table
  descli.ts           tool-description quality linter
  serverConfig → platform/serverConfig.ts  server-row ↔ runtime codec
    skills.ts         loads skills/*.md (frontmatter) into the skills hub
    crypto.ts         AES-256-GCM secret encryption + SHA-256 token hashing
  proxy/
    upstream.ts       v2 client connection to one stdio/HTTP MCP server, namespacing
    aggregator.ts     connect-all / list-all / route-calls across upstreams
  builtins/           time, uuid, fetch, memory, filesystem, knowledge, github,
                      jira, search, postgres, sqlite, notion, slack, crypto, hn,
                      weather (+ the skills module)
skills/               *.md — the skills hub library (one markdown file per skill)
public/
  index.html          built React dashboard (emitted by `npm run build:web`)
  assets/             hashed JS/CSS bundles (React + Astryx + Tailwind)
web/                  the dashboard source — React 19 + Vite + Tailwind CSS v4
                      (layout utilities only), Meta's Astryx design system
                      (@astryxdesign/core + theme-neutral, forced dark),
                      lucide-react (icons)
  src/
    App.tsx           root: session gate + view router + toast viewport
    main.tsx          Astryx Theme provider (neutral theme, dark mode)
    lib/api.ts        REST client + types
    lib/store.tsx     app state: session, data, routing, toasts
    lib/catalog.ts    MCP Directory catalog + connect-guide client configs
    components/       Shell (AppShell + TopNav + SideNav), ui primitives
    views/            Auth, Dashboard, Directory, Connect, Servers, Tokens,
                      Credentials, Modules, Skills, Settings
registry/
  server.json           official MCP Registry entry (publish-ready)
  server.schema.json    vendored registry schema (offline validation)
scripts/
  smoke.mjs           core end-to-end test (npm test)
  smoke-platform.mjs  platform-mode end-to-end test (npm run test:platform)
  smoke-ghjira.mjs    GitHub + Jira mock-API test
  test-upstream.mjs   tiny stdio MCP server used by the platform test
tests/
  *.test.ts           unit tests for core modules (npm run test:unit) —
                      utils/config/ratelimit/audit, run via node --test + tsx
docs/
  ARCHITECTURE.md     how the pieces fit together

Roadmap ideas

• MRTR (Multi Round-Trip Requests) — tools that ask the user to confirm mid-call (e.g. before creating a GitHub issue), via input_required results

• Per-user keys for built-in modules (currently server-level env keys are shared)

• Tasks extension for long-running agent work

• Resource + prompt aggregation from upstreams (currently tools only)