MCP Troubleshooting

“Not authenticated” Error

Ensure you’ve logged in:

pretorin login
pretorin whoami  # Verify authentication

Five global tools are served without a platform client and keep working while unauthenticated: check_context, get_cli_status, get_instructions, list_tools, and search_platform_capabilities. The normal profile’s local check_campaign_runtime, get_campaign, list_campaigns, and cancel_campaign also continue during a platform auth or consent outage. Preview, start, and resume still need current authority. If the global tools respond but other platform-backed calls return “Not authenticated”, the transport is healthy and the problem is credentials— ask the agent to call check_context and read its connected field and suggested_next hint.

MCP Server Not Found

Verify pretorin is installed and in your PATH:
```
which pretorin
pretorin --version
```

Try using the full path in your configuration:

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

For uv tool or pipx installations, find the path:
```
command -v pretorin
```
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 runs six check groups: check_context across all grounding states, list_tools tier classification, get_instructions routing markers, get_workflow bundling required_tool_schemas, the workflow-routing error path producing a structured workflow_required payload, and the recipe-context guard producing a recipe_required payload. The last two also assert that exactly one PRETORIN_TELEMETRY_EVENT line is emitted on stderr with the matching event_type. 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.

Truncated Tool Results

Every tool result is measured against a byte budget at the server boundary before it is returned, so a single result can never overflow the MCP host’s tool-result cap and force a spill to disk. The default budget is 40 KB; override it with PRETORIN_MCP_MAX_RESULT_BYTES for hosts that tolerate larger payloads (a malformed or non-positive value falls back to the default).

When a result is over budget, the guard bounds result lists first — marking each with a {key}_truncated_count — and only as a last resort returns a summary payload shaped like this:

{
  "response_guard": {
    "truncated": true,
    "original_bytes": 91234,
    "budget_bytes": 40000,
    "recovery": "Re-run with narrower scope ..."
  }
}

Truncation is always marked explicitly, and record-internal data (control mappings, tags) is never silently dropped. If you see this payload, narrow the request rather than raising the budget: ask for one control, id, or query at a time, or use the tool’s own detail and pagination knobs (check_sources for a single control, search_evidence with snippet_only, list_org_policies). Error results are left untouched by the guard.

Campaign lifecycle results have a stricter internal 32 KiB budget. Request a smaller immutable item page with get_campaign.offset/limit, or continue a Campaign list with its opaque cursor. The adapter may safely return fewer rows than requested and will include continuation metadata.

Campaign runtime setup required

Call check_campaign_runtime before preview_campaign. If it returns launch_ready=false, do not preview: inspect the first structured blocker, including its component, required/detected versions, and remediation. A missing or mismatched Python dependency points to pretorin update 0.29.10. Run that outside MCP, restart the MCP server so the repaired environment is loaded, and call check_campaign_runtime again.

The standard package includes the Campaign Python dependencies; the former campaign-runner extra is a compatibility-only alias. Missing managed native components may appear under deferred_setup with timing: "after_explicit_start_confirmation"; they do not permit skipping the START gate. Configured/PATH executables may instead appear under deferred_validation; their path and content identity are frozen without a launch, and version/capability validation waits for explicit START. Textual observer readiness is reported separately from headless execution readiness.

Campaign observer or project error

The observer.command and observer.uvx_command values in a Campaign result are suggestions, not server actions. Copy one into a terminal on the same host as the MCP server. A terminal on the remote client cannot see the server host’s local Campaign/Plan stores. Use the supplied version-matched uvx --from "pretorin==0.29.10" command for an isolated observer environment.

campaign_invalid_project means project_dir did not resolve beneath the MCP startup root or an entry in PRETORIN_MCP_ALLOWED_PROJECT_ROOTS. Verify that the path exists, is not a filesystem root, stays within its canonical root after symlink and Git-root resolution, and uses the operating-system path separator in the environment variable (: on POSIX, ; on Windows).

Unexpected Output on stderr

The server writes two kinds of non-JSON-RPC lines to stderr. Both are by design — stdout carries only JSON-RPC — but they can look like faults in a host that surfaces stderr as errors:

NOTICE: ... at startup when a newer CLI version is available. Silence it with PRETORIN_DISABLE_UPDATE_CHECK=1 or pretorin config set disable_update_check true.
PRETORIN_TELEMETRY_EVENT {...} single-line JSON events for routing and recipe-context bypasses. These stay on the local machine — no content or PII is included. Silence them with PRETORIN_MCP_TELEMETRY_DISABLED=1. See Tool Reference — Telemetry.

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

Error	Fix
`ac-1` not found	Use zero-padded: `ac-01`
`ac` family not found	Use slug: `access-control`
`AC.l2-3.1.1` not found	CMMC is case-sensitive: `AC.L2-3.1.1`
`3.1.1` control not found	800-171 needs leading zeros: `03.01.01`

Documentation: platform.pretorin.com/api/docs
Issues: github.com/pretorin-ai/pretorin-cli/issues
Platform: platform.pretorin.com

Pretorin Developer & Agent Docs