@systemdox/mcp-server

Your architecture, in your agents' context window.

SystemDox is the document plane for AI-assisted engineering: your standards — specs, architecture decision records, checks, project rules, docs — versioned in git and delivered into your coding agents' context at write time. This MCP server is how Claude Code, Cursor, and any MCP-compatible tool read that context — and write decisions back.

Why teams use it

• Write-time context — get_context ranks the checks, specs, and docs relevant to the task at hand and fetches their bodies within a token budget, so the agent starts from your architecture instead of guessing it.
• Both directions — agents call report_decision and update_spec as they work, so decision records exist as a by-product of shipping, not as archaeology afterwards.
• One source for every agent — no per-developer rules-file forks; every session in every repository starts from the same governed, versioned context.
• Scoped by key — the API key is the boundary: a department-scoped key sees only its own space's checks, specs, and docs.

Get started in about a minute

1. SystemDox is in private preview. Request early access to get a workspace.
2. Connect a GitHub repository.
3. Paste https://<your-workspace>.mcp.systemdox.com/connect into Claude and sign in, or generate an API key (workspace settings) and add the server to your tool — hosted (Option A) or local (Option B) below.

Docs: MCP setup guide · Documentation standard · Why write-time context

---

Connect by signing in

Your workspace has its own address. Paste it into Claude's Settings → Connectors, or run:

claude mcp add --transport http systemdox https://<your-workspace>.mcp.systemdox.com/connect

Your browser opens SystemDox. Sign in with your passkey and approve; if your account has no passkey yet, the page offers to add one. It only reads unless you choose to allow writes. Claude holds a token for an hour, renewed for you, and the API key behind the connection stays with SystemDox. Only an owner or admin of the workspace can connect this way for now.

With an API key

There are two more ways to run it, for scripts, CI and other tools. Both authenticate with a SystemDox API key (generate one on your SystemDox settings page) and act strictly as the caller — every tool call is scoped to that key's tenant.

Option A — Hosted endpoint (no install)

SystemDox hosts the server at a per-tenant subdomain, speaking MCP Streamable HTTP. Point any HTTP-capable MCP client at it — nothing to install or update.

{
  "mcpServers": {
    "systemdox": {
      "type": "http",
      "url": "https://<your-workspace>.mcp.systemdox.com/mcp",
      "headers": {
        // Reference the key via an env var — never commit the literal key.
        "Authorization": "Bearer ${SYSTEMDOX_API_KEY}"
      }
    }
  }
}

Never commit the literal key. The pweb_ prefix is deliberately scanner-friendly, and a key in a committed .mcp.json is a long-lived read/write credential retained in git history across every clone, fork, and CI log. MCP clients that expand environment variables in .mcp.json (e.g. Claude Code) resolve ${SYSTEMDOX_API_KEY} at load time; deliver the value from your shell, a secret manager, or your CI secret store. For clients that don't expand variables, inject the key at deploy time and keep the file untracked.

• URL — https://<your-workspace>.mcp.systemdox.com/mcp. <your-workspace> is your tenant's slug; it must match the tenant that owns the API key, or the request is rejected 403. Set a slug on the workspace first (owner/admin → workspace settings) if you don't have one.
• Auth — the key must be sent as Authorization: Bearer <key>. (An X-API-Key-only request is rejected at the gateway.)
• Transport — stateless request/response (JSON); each call is independent, which suits serverless hosting. There is no long-lived SSE stream.
• Scope — the key is the boundary. A key bound to a single space (a "department" key) sees only that space's context; org-wide planner endpoints (get_planning_context, get_plan_board) are barred to it and answer 403. Give each department's repo its own key via ${SYSTEMDOX_API_KEY}, and an agent in one department never sees another's checks, specs, or docs.

Option B — Local (stdio) via npx

Run the server locally as a stdio subprocess of your MCP client. Useful offline, or when you'd rather not depend on the hosted endpoint.

npx @systemdox/mcp-server setup

…or configure it directly:

{
  "mcpServers": {
    "systemdox": {
      "command": "npx",
      "args": ["@systemdox/mcp-server"],
      "env": {
        // Provided by your shell / secret store — not committed in the file.
        "SYSTEMDOX_API_KEY": "${SYSTEMDOX_API_KEY}"
      }
    }
  }
}

The package is published to the public npm registry — npx resolves it with no registry configuration and no credentials.

Environment variables (stdio mode)

Variable	Required	Default	Purpose
SYSTEMDOX_API_KEY	no	the key in ~/.claude/systemdox/credentials.json	Your SystemDox API key. setup stores it in ~/.claude/systemdox/credentials.json and nowhere else, so the server reads it there when this is not set
SYSTEMDOX_WORKSPACE	no	—	The workspace whose key to read when credentials.json holds several
SYSTEMDOX_API_URL	no	https://api.puglieseweb.com/systemdox	REST API base URL
SYSTEMDOX_CACHE_TTL	no	300	Response cache TTL (seconds)

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗