MCP Troubleshooting

“Not authenticated” Error

Ensure you’ve logged in:

pretorin login
pretorin whoami  # Verify authentication

Five 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. If those respond but everything else returns “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.

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