@systemdox/mcp-server

@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

• Create a SystemDox workspace — the free tier covers one repository, permanently.
• Connect a GitHub repository and generate an API key (workspace settings).
• Add the server to your tool — hosted (Option A) or local (Option B) below.

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

There are two ways to run it. 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	yes	—	Your SystemDox API key
SYSTEMDOX_API_URL	no	https://api.puglieseweb.com/systemdox	REST API base URL
SYSTEMDOX_CACHE_TTL	no	300	Response cache TTL (seconds)

Tools

Read: get_checks, get_specs, get_docs, get_tech_stack, get_planning_context, get_plan_board, get_context, get_project_rules, get_prompt_templates. Write: create_check, update_spec, report_decision, create_project_rule, create_prompt_template. Write tools require an API key with editor+ role.

get_context

The aggregator. It ranks checks, specs and docs against the task, then spends the token budget fetching the bodies of the highest-ranked specs and docs (/v1/specs/{id}, /v1/docs/{id}/content) — concurrently, clipped to a fair share of what's left. Every item carries the spec_id / doc_id needed to fetch it in full, so nothing is a dead end: items whose body did not fit, or whose fetch failed, still appear as a title + ID. Tech stack and project rules are always included; the budget is spent on bodies, never on truncating the list. Retrieval quality is measured by eval/ — see eval/README.md.

Deprecated tool names

get_guardrails and create_guardrail were renamed to get_checks and create_check. The old names still work. They are registered as aliases of the same handlers and accept the same arguments, so an .mcp.json or agent permission allowlist that pins them keeps working unchanged.

Old name	New name	Removed no earlier than
get_guardrails	get_checks	2027-01-31
create_guardrail	create_check	2027-01-31

Removal also requires usage telemetry showing no calls against the old name. The /guardrails/* REST routes are not deprecated and are not changing.

Development

pnpm install         # from the monorepo root (pnpm workspace)
pnpm --filter @systemdox/mcp-server build       # tsup + tsc
pnpm --filter @systemdox/mcp-server test        # unit tests (node:test)
pnpm --filter @systemdox/mcp-server test:http   # offline handler smoke test
pnpm --filter @systemdox/mcp-server eval        # get_context retrieval eval
node scripts/mcp-release-gate.mjs               # from the monorepo root

Entry points: src/index.ts (stdio), src/http.ts (hosted HTTP handler), src/cli.ts (setup command). Tool registration is shared via src/server.ts (createServer). The hosted handler is deployed as a Lambda by the product-systemdox backend stack (systemdox-backend-prod), reached through the *.mcp.systemdox.com custom domain.

Publishing

.github/workflows/mcp-server-publish.yml publishes to registry.npmjs.org under the public @systemdox scope, authenticating with the NPM_TOKEN repo secret. The publish step uses a throwaway npmrc containing only the public registry: the repo-root .npmrc maps @puglieseweb to GitHub Packages (needed for installing the org's private packages) and must never leak into a publish of this package — that is how it previously landed in a private registry that npx 404s for every customer.

scripts/mcp-release-gate.mjs is the standing guard: it reads the install command out of the product source and runs it against the public registry with no org credentials.