## 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

## 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`

## 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

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