Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MCP Troubleshooting

“Not authenticated” Error

Ensure you’ve logged in:

pretorin login
pretorin whoami  # Verify authentication

MCP Server Not Found

  1. Verify pretorin is installed and in your PATH:

    which pretorin
pretorin --version

  2. Try using the full path in your configuration:

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

  3. For uv tool or pipx installations, find the path:

    command -v pretorin

  4. If the MCP client can talk to Pretorin but scoped write tools behave strangely, validate the stored CLI context:

    pretorin context show --quiet --check

    This catches deleted systems, detached frameworks, and other stale local scope before you debug the MCP client itself.

Server Crashes or Hangs

Check the MCP server logs:

pretorin mcp-serve 2>&1 | tee mcp-debug.log

Ensure your API key is valid:

pretorin whoami

Smoke-test the MCP Surface

pretorin mcp-smoke-test runs the cross-harness tool surface end-to-end against the in-process handlers (no MCP client required). It exercises check_context across all grounding states, validates list_tools tier classification, asserts the workflow-routing error path produces a structured workflow_required payload, and verifies get_workflow bundles required_tool_schemas. Each check prints PASS/FAIL; exit code 1 on any failure.

pretorin mcp-smoke-test

Use this to confirm the server’s tool dispatch and routing logic are healthy before debugging the MCP host or transport.

Framework or Control Not Found

  • Verify the framework ID exists: pretorin frameworks list
  • Verify the control ID exists: pretorin frameworks controls <framework_id>
  • Check Control ID Formats for correct formatting

Common ID Mistakes

ErrorFix
ac-1 not foundUse zero-padded: ac-01
ac family not foundUse slug: access-control
AC.l2-3.1.1 not foundCMMC is case-sensitive: AC.L2-3.1.1
3.1.1 control not found800-171 needs leading zeros: 03.01.01

No Systems Found

If list_systems returns no systems, you need a beta code to create one on the Pretorin platform. Systems cannot be created through the CLI or MCP. Sign up for early access.

Rate Limiting

The API uses rate limiting. If you receive 429 Too Many Requests errors, the client automatically retries with exponential backoff. For persistent issues, reduce request frequency.

Support