Systemdox

@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:// .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:// .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:// .mcp.systemdox.com/mcp. 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 . (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)

Tools

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

Skills (ADR-216): publish_skill, list_skills, install_skill. A Claude Code skill folder (SKILL.md plus its references and scripts) is published whole; publishing a name again makes a new version. In stdio mode the server reads and writes the folder itself (publish_skill { directory }, install_skill { name } into ~/.claude/skills/ /), refusing to replace a file edited since it was installed unless overwrite is set. In hosted mode the agent passes and writes the files. Without an agent:

npx -y @systemdox/mcp-server install-skill <name> [--version n] [--target dir] [--overwrite]

Exit codes: 0 installed, 1 usage / no key / API error, 2 refused because files there were edited.

What every session is told (ADR-223)

Installing this server is enough for a computer to know what its team uses. When a session connects, the server answers with instructions, which Claude Code puts in the session's system prompt with no tool call:

• the workspace, and to call get_context before writing code;
• each skill your team put in the team setup, with when to use it;
• what this computer lacks. A missing or older skill is installed with install_skill, which writes files and runs nothing. A file you edited is never replaced, and a folder that did not come from SystemDox is left alone.

Hooks, MCP servers, team instructions and memory run or load by themselves, so they still wait for you: setup, in your own terminal, below. An agent never answers its prompts. So does a team skill that is not plain (anything in its frontmatter beyond a name and a description, files outside its own folders, or a !-command) or that sits outside the default space: a session is told its name and not to install it. A skill may not hold .claude-plugin/, which would make it a plugin. The hosted server cannot see your disk, so it says how to check.

`get_team_setup` (both servers, read-only) answers the same question in full: every skill, hook command and MCP server, and on your own computer what is missing and what to do. Use it with a client that does not surface instructions.

If this computer has no key, or SystemDox refuses it, the server still connects and tells the session what to do. See the words a session gets in the console, under Docs › Team setup › What every session is told.

Team setup (ADR-217)

Your workspace's Claude Code setup (hooks, MCP servers, agents, commands, the skills your team chose, and one team CLAUDE.md) is published to SystemDox and reaches every member's computer as one plugin, -setup.

• `publish_setup_part` (both servers) publishes one part: hooks (hooks/hooks.json and the scripts/ it calls), mcp (.mcp.json), agents (agents/*.md), commands (commands/*.md) or instructions (CLAUDE.md). On your own computer pass directory: only the files the part accepts are read, and a link, a binary file or a file over the limits stops it before anything is sent. Every part but instructions makes a new plugin version, which each member accepts at their next update. For mcp, every env and headers value is replaced by a ${NAME} reference to each member's own environment variable. Publishing any part needs build:write on the default space (SYD-A001 otherwise); only an admin or owner mints such a key, and each member accepts every new plugin version in their own terminal.
• `resolve_person` (both servers) reads back a person a team memory names by identifier ( `con_…` (reseller, sales) ): their label, name, phone number and email address. The details are for that session only; the memory keeps the identifier. It writes nothing.
• `sync_memory` (your own computer only) syncs a project's team memory, as sync-memory below does with no one at the terminal: it never answers a question about a person and never rewrites a file for one. A file that still holds a phone number, an email address or a home-folder path is skipped and listed with the command to run yourself. Inputs: project, dryRun.

How the team memory works, for a member and for a team lead, is in the guide Team memory.

One command sets up your computer, and the same command updates it:

npx -y @systemdox/mcp-server setup [--project <name>] [--dir <checkout>] [--import <folder>]... [--yes] [--overwrite] [--choose]

• The key must be able to sync. In the console, Settings › API keys, press Key for Claude Code team setup. A key made with the form's defaults is a Reader key: it reads the team setup, but SystemDox refuses its pushes (SYD-A001), so it cannot sync a team memory.
• The key is kept. On a computer that already has a key (in SYSTEMDOX_API_KEY, or stored by an earlier setup), setup shows it by its last four characters, as the console lists keys: press Enter to keep it, or paste a new key to replace it. A key is never shown as you paste it. A kept key that SystemDox refuses (revoked or expired) is replaced once, at the same prompt. The API URL and the AI tools are asked once; --choose asks again.
• The workspace's first team memory needs a name. With no team memory yet, setup asks for one at a terminal (Enter skips it), or take it from --project . Later computers find the only team memory by themselves, and with several they ask which is the checkout's.
• A key that cannot sync is caught first. Before it shows anything, setup asks SystemDox whether the key may push the project (blobs/missing w