MCP Server Setup

What Is the MCP Server?

The Model Context Protocol (MCP) is an open standard that lets AI tools read from and write to external systems. The SystemDox MCP server exposes your organisation’s standards as tools that AI assistants can call directly.

Instead of copy-pasting rules into prompts or hoping the AI remembers your conventions, the MCP server injects the right context automatically. Your AI assistant can read your checks before writing code, consult your specs before planning, and even create new checks when it discovers patterns worth enforcing.

Compatibility

Supported AI Tools

Any tool that supports the Model Context Protocol can connect to SystemDox.

Claude Code

Anthropic’s CLI and IDE extension. Configure per-project via .mcp.json or user-wide via ~/.claude/.mcp.json.

Cursor

AI-first code editor. Configure via .cursor/mcp.json or global settings.

Any MCP Client

Any tool supporting MCP stdio transport. Configure the server command and environment variables.

Before You Start

Prerequisites

SystemDox account

API key

Generate in Settings → API Keys

Node.js 18+

Required to run the MCP server via npx

An MCP-compatible AI tool

Claude Code, Cursor, or any MCP client

Step by Step

Setup

Run it locally (automatic or manual), or skip the install entirely with the hosted endpoint.

Prefer zero-install? Use the hosted endpoint

SystemDox hosts the MCP server at your workspace subdomain over MCP Streamable HTTP — nothing to install or keep updated. Point any HTTP-capable MCP client at it and authenticate with your API key. Your workspace must have a slug matching the subdomain.

{
  "mcpServers": {
    "systemdox": {
      "type": "http",
      "url": "https://<your-workspace>.mcp.systemdox.com/mcp",
      "headers": { "Authorization": "Bearer your-api-key-here" }
    }
  }
}

A Automatic Setup (Recommended)

Run the interactive setup command. It detects your installed AI tools, validates your API key, and writes the configuration file automatically. Choose project scope to configure a single repo, or user scope to enable SystemDox across all your projects at once.

npx @systemdox/mcp-server setup

The wizard will prompt you for:

API key — your SystemDox API key (validated against the API)
Target and scope — Claude Code (project or user), Cursor (project or global), VS Code, or all detected targets

After setup, restart your AI tool and the SystemDox tools will be available immediately.

The package is @systemdox/mcp-server on the public npm registry — no credentials or registry configuration needed — and the server is listed in the official MCP Registry as io.github.puglieseweb/systemdox.

B Manual Configuration

Get Your API Key

Log in to app.systemdox.com, navigate to Settings → API Keys, and generate a new key. Copy it — you will need it in the next step.

Create the Configuration File

Choose one of the following options:

Option 1: Per-project — Create a .mcp.json file in your project root (for Claude Code) or .cursor/mcp.json (for Cursor):

// .mcp.json (project root)
{
  "mcpServers": {
    "systemdox": {
      "command": "npx",
      "args": ["@systemdox/mcp-server"],
      "env": {
        "SYSTEMDOX_API_KEY": "your-api-key-here",
        "SYSTEMDOX_API_URL": "https://api.puglieseweb.com/systemdox"
      }
    }
  }
}

Option 2: User-wide (all projects) — Add the server to ~/.claude/.mcp.json so it is available in every Claude Code project without per-repo configuration:

// ~/.claude/.mcp.json (user scope — all projects)
{
  "mcpServers": {
    "systemdox": {
      "command": "npx",
      "args": ["@systemdox/mcp-server"],
      "env": {
        "SYSTEMDOX_API_KEY": "your-api-key-here",
        "SYSTEMDOX_API_URL": "https://api.puglieseweb.com/systemdox"
      }
    }
  }
}

Restart and Verify

Restart your AI tool. The SystemDox MCP server starts automatically when the tool reads the configuration. Verify by asking your AI assistant:

# Ask your AI assistant:

“Use the get_context tool to show me my SystemDox standards.”

If configured correctly, the assistant will return your tech stack, checks, project rules, and relevant specs.

Reference

Environment Variables

Variable	Required	Default	Description
`SYSTEMDOX_API_KEY`	Yes	—	Your SystemDox API key
`SYSTEMDOX_API_URL`	No	api.puglieseweb.com/systemdox	API base URL
`SYSTEMDOX_CACHE_TTL`	No	300	Cache duration in seconds
`SYSTEMDOX_DEFAULT_ORG`	No	—	Default GitHub organisation

Capabilities

Available Tools

Once connected, your AI assistant can call these tools to read and write your standards.

Read Tools

get_context

Intelligent aggregator — fetches checks, rules, specs, docs, and tech stack, then ranks by relevance to your current task within a token budget. Start here.

get_checks

Retrieve coding checks (banned patterns, required patterns). Filter by language, category, or file path. Formerly get_guardrails, which still works.

get_project_rules

Retrieve project rules — team-defined principles covering deployment, architecture, security, testing, and process.

get_prompt_templates

Retrieve reusable prompt templates for common AI tasks like code reviews or documentation generation.

get_specs

Retrieve specifications in shared-specs format (proposal + RFC 2119 requirements + Given/When/Then scenarios).

get_docs

Retrieve synced documentation from connected GitHub repositories. Filter by repo, path, or keyword.

get_tech_stack

Return the configured tech stack (name, version, category, notes).

get_planning_context

Org-wide documentation context: repo summaries (purpose, conventions, CLAUDE.md), cross-repo dependencies, ADR titles and spec titles.

get_plan_board

Read-only view of the connected GitHub Projects boards: open boards with item counts by status, or the issues on one board grouped into In Progress / Todo / Done with number, repo, labels, assignees and URL.

Write Tools

create_check

Push a new check back to SystemDox when you discover a pattern that should be enforced. Formerly create_guardrail, which still works.

create_project_rule

Create a new project rule with text and category (deployment, architecture, security, testing, process).

create_prompt_template

Create a reusable prompt template with name, description, and prompt content.

update_spec

Update a draft spec with new scenarios, requirements, or tasks.

report_decision

Record an architecture decision as a draft ADR in SystemDox.

In Practice

Usage Examples

Here are some things you can ask your AI assistant once the MCP server is connected.

Get context before coding

“I’m about to add a new REST endpoint for user preferences. Use get_context to check what standards I should follow.”

The AI calls get_context with your task description, gets relevant checks (auth patterns, error handling), project rules (deployment via CI), and specs — then writes code that follows them.

Create a check from a code review

“I just noticed you used console.log instead of our structured logger. Create a check in SystemDox to ban console.log in production code.”

The AI calls create_check with the banned pattern, correct fix, and a fitness test command — making the rule permanent.

Check project rules before deploying

“Before I merge this, check our project rules to make sure I’m not violating any deployment or process standards.”

The AI calls get_project_rules filtered by deployment and process categories, then reviews your changes against those rules.

Frequently Asked Questions

Do I need to install the MCP server globally?

No. Using npx in your configuration downloads and runs the server on demand. There is nothing to install or update manually. If you want SystemDox available in all your projects, use the user-scope option during setup — it writes to ~/.claude/.mcp.json instead of a per-project file.

Is my API key sent to the AI model?

No. The API key is used only by the MCP server process to authenticate with the SystemDox API. It is passed as an environment variable and never included in the data sent to the AI model.

Can I use the same configuration across multiple projects?

Yes. The recommended approach is user-scope installation: select the “Claude Code (user — all projects)” target during setup, or manually add the server to ~/.claude/.mcp.json. This makes SystemDox available in every project without copying .mcp.json to each repo. For Cursor, select the “Cursor (global)” target.

Does the MCP server cache API responses?

Yes. Read operations are cached for 5 minutes by default (configurable via SYSTEMDOX_CACHE_TTL). Write operations automatically invalidate the relevant cache entries.

Should I commit .mcp.json to version control?

It depends. You can commit the file without the API key (leaving SYSTEMDOX_API_KEY as a placeholder) so teammates see the server is configured, and each developer sets the actual key in their local environment. Never commit a real API key to version control.