MCP Setup Guides

Prerequisites

Install and authenticate the Pretorin CLI:

uv tool install pretorin
pretorin login

The standard package contains the exact Hatchet SDK and Textual dependencies required by Plan-backed Campaigns. The former campaign-runner extra remains a compatibility-only alias; manual and MCP Registry launches now use the same base package. To reproduce the current Registry environment directly:

uvx --from 'pretorin==0.29.10' \
  pretorin mcp-serve

The registry process does not automatically open a terminal UI. A single-Campaign MCP response supplies a same-host observer command and this version-matched alternative:

uvx --from 'pretorin==0.29.10' \
  pretorin campaign watch <campaign-plan-id>

The command is a suggestion only; the MCP server never executes it. Run it on the same machine as the MCP server because the Campaign and Plan stores are local and cannot be attached from or migrated to another host.

Before preview_campaign, call check_campaign_runtime. It is a local, inspection-only gate and returns execution dependencies, selected agent and embedded Hatchet runtimes, optional observer readiness, blockers, deferred managed setup, deferred configured/PATH executable validation, and remediation. If launch_ready=false, stop. After applying the remediation outside MCP, restart the MCP process and call the check again. Preview is the first operation that may contact the platform, run the shared source preflight, reserve an idempotency key, or persist Campaign Plans.

Install the Pretorin Skill

The skill teaches your AI agent how to use MCP tools for compliance workflows — control ID formats, narrative authoring rules, gap analysis methodology, and more. Install it before setting up MCP:

pretorin skill install                # both Claude Code and Codex CLI
pretorin skill install --agent claude # Claude Code only
pretorin skill install --agent codex  # Codex CLI only
pretorin skill status                 # check what's installed
pretorin skill uninstall              # remove it again

The skill is copied to ~/.claude/skills/pretorin/ and/or ~/.codex/skills/pretorin/ and auto-discovered by each agent. Add --force to overwrite an existing installation, --path to install into a directory for an agent that isn’t in the built-in registry, and pretorin skill list-agents to see the known agents and their skill directories.

Claude Code

Quick setup — run a single command:

claude mcp add --transport stdio pretorin -- pretorin mcp-serve

This registers the server for your current project. To make it available across all your projects, add --scope user.

Team setup — add a .mcp.json file to your project root so every team member gets the server automatically:

{
  "mcpServers": {
    "pretorin": {
      "type": "stdio",
      "command": "pretorin",
      "args": ["mcp-serve"]
    }
  }
}

Claude Code detects the file automatically.

Claude Desktop

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pretorin": {
      "command": "pretorin",
      "args": ["mcp-serve"]
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pretorin": {
      "command": "pretorin",
      "args": ["mcp-serve"]
    }
  }
}

Restart Cursor after saving.

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.pretorin]
command = "pretorin"
args = ["mcp-serve"]

If you installed Pretorin with uv tool install or pipx, prefer pinning the absolute path from command -v pretorin to avoid PATH drift between shells and GUI apps.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pretorin": {
      "command": "pretorin",
      "args": ["mcp-serve"]
    }
  }
}

Restart Windsurf after saving.

Other MCP Clients

The Pretorin MCP server follows the standard Model Context Protocol and works with any MCP-compatible client. The server communicates via stdio.

To check the server’s own tool dispatch and routing before wiring up a host, run the built-in smoke test — it exercises the handlers in-process, so no MCP client is required:

pretorin mcp-smoke-test

To test the transport manually:

pretorin mcp-serve

The server accepts JSON-RPC messages on stdin and responds on stdout. stdout carries JSON-RPC only — the update notice and the routing telemetry events both go to stderr, so a host that merges the two streams will see protocol errors. See Troubleshooting — Unexpected Output on stderr for the two line formats and how to silence each.

Additional Campaign project roots

By default, MCP Campaign tools accept only the canonical project root from which the server started. To expose another trusted local workspace, configure PRETORIN_MCP_ALLOWED_PROJECT_ROOTS on the MCP server process. Separate roots with the operating system path separator (: on POSIX, ; on Windows):

export PRETORIN_MCP_ALLOWED_PROJECT_ROOTS="/work/compliance:/work/services"

Only preview_campaign and list_campaigns accept project_dir; every later single-Campaign operation resolves the exact Campaign Plan ID within the authorized stores. Each configured directory must exist and resolve to a safe non-root location. Traversal, symlink escape, filesystem roots, and Git roots outside the authorized directory fail with campaign_invalid_project.

PATH Considerations

If your AI tool can’t find the pretorin command, use the full path:

# Find the full path
command -v pretorin

Then use that path in your configuration:

{
  "mcpServers": {
    "pretorin": {
      "command": "/home/user/.local/bin/pretorin",
      "args": ["mcp-serve"]
    }
  }
}

This is especially important for uv tool and pipx installations where the binary may not be on the PATH available to GUI applications.

Before debugging scoped MCP write failures, validate the active CLI scope:

pretorin context show --quiet --check