ClickProbe IDE Integration — Troubleshooting

1. Keychain denial / prompt on first save

macOS: On first clickprobe-proxy login, macOS shows a Keychain access prompt for the app. Click Allow. If you accidentally denied:

• Open Keychain Access, search for clickprobe-proxy, delete the entry.
• Re-run clickprobe-proxy login.

Linux (GNOME/KDE): clickprobe-proxy stores tokens via the freedesktop Secret Service (Seahorse / KWallet). If you see a dialog asking to unlock the keyring, enter your login password. If D-Bus is absent (e.g. headless server), the proxy falls back to an encrypted file store and prints a warning — that is expected.

Windows: Credential Manager is used automatically. No prompt should appear. If access is denied by a corporate policy, run with --storage file to use the encrypted-file fallback: clickprobe-proxy login --storage file.

2. 401 loops after get_bugs or other tool calls

The proxy’s access token may be expired or revoked.

Fix:

clickprobe-proxy logout
clickprobe-proxy login

Restart your IDE after re-logging in (some IDEs cache the MCP server subprocess).

If the 401 persists, check that the account is not suspended at https://app.clickprobe.ai/app/billing.

3. Windows path quoting in .mcp.json / mcp_settings.json

Use double-backslash (\\) for Windows paths in JSON:

{
  "mcpServers": {
    "clickprobe": {
      "command": "C:\\Users\\you\\bin\\clickprobe-proxy.exe",
      "args": ["--agent-stdio"]
    }
  }
}

Forward slashes also work in most contexts:

{
  "mcpServers": {
    "clickprobe": {
      "command": "C:/Users/you/bin/clickprobe-proxy.exe",
      "args": ["--agent-stdio"]
    }
  }
}

Do not use a path with spaces without quoting. Prefer to install clickprobe-proxy to a path without spaces (e.g. C:\bin\ or add it to %PATH% and use "command": "clickprobe-proxy").

4. WSL: which clickprobe-proxy returns nothing

The proxy binary is a native Linux binary. In WSL:

1. Build or download the Linux binary.
2. Add to ~/.bashrc:

   export PATH="$HOME/.local/bin:$PATH"

3. Copy the binary: cp clickprobe-proxy ~/.local/bin/ && chmod +x ~/.local/bin/clickprobe-proxy
4. Verify: which clickprobe-proxy

Note: WSL2 by default has no DISPLAY, so clickprobe-proxy login will auto-detect headless mode and use the device-code flow. If you have WSLg set up (DISPLAY=:0 present), it may attempt browser mode first.

5. Docker container: no D-Bus, no keychain

Inside a Docker container, the OS-native keystore is unavailable. The proxy automatically falls back to an encrypted file store:

clickprobe-proxy: keychain unavailable (<reason>); falling back to encrypted file at /root/.local/share/clickprobe/tokens-v1.enc

This is expected. To persist tokens across container restarts, mount a volume:

docker run -v clickprobe-tokens:/root/.local/share/clickprobe my-image

Or use --storage file explicitly to prevent the keychain attempt: clickprobe-proxy login --storage file.

6. Device-code phishing — what the machine label means

When you visit https://app.clickprobe.ai/auth/device and enter a code, the consent page shows the machine label of the proxy that initiated the request (e.g. "laptop" or "ci-runner-01").

The label is self-reported by the proxy. It is not verified by ClickProbe. An attacker could create a proxy that reports a convincing-looking label.

What to do: If you did not just run clickprobe-proxy login --device on the machine shown, click Deny. The code expires in 10 minutes; the attacker’s session never gets a token.

7. tools/list returns 0 tools — proxy not logged in

If your IDE reports no tools from the clickprobe MCP server, the proxy most likely has no stored token.

Fix:

clickprobe-proxy login

Then restart your IDE (the --agent-stdio subprocess is spawned fresh on each IDE start).

To verify the proxy is working without an IDE:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | clickprobe-proxy --agent-stdio

Expected: a JSON response listing 9 tools.

8. Browser didn’t open during clickprobe-proxy login

If the browser doesn’t open, the proxy falls back to device-code mode automatically. Alternatively, force device mode:

clickprobe-proxy login --device

Or force browser mode to see the error:

clickprobe-proxy login --browser --verbose

--verbose shows the URL that would be opened. You can copy-paste it into your browser manually.

9. 422 on resolve_bug — bug FSM forbids the transition

When you call clickprobe.resolve_bug on a bug that is in status new (or any other status that cannot transition directly to resolved), the proxy returns:

{
  "detail": {
    "reason": "illegal_transition",
    "current": "new",
    "allowed": ["confirmed", "dismissed", "exported", "retesting"]
  }
}

Why: The server-side FSM forbids new → resolved. Only bugs in status confirmed, retesting, or exported can move to resolved.

Fix — confirm the bug first:

Option A (operator click — recommended):

1. Open https://app.clickprobe.ai/app/bugs/{bug_id} in the dashboard.
2. Click Confirm.
3. Retry the clickprobe.resolve_bug call.

Option B (operator API call — for scripting / batch confirms):

# Operator's browser session cookie (not the agent's proxy token)
curl -X PATCH "https://app.clickprobe.ai/api/bugs/<bug_id>" \
     -H "Cookie: <operator-session-cookie>" \
     -H "Content-Type: application/json" \
     -d '{"status": "confirmed"}'

Then retry clickprobe.resolve_bug.

Note: A clickprobe.confirm_bug MCP tool that would let the agent skip the operator round-trip is tracked as a follow-up (C-014-F01); shipping it is a v1.x decision based on beta-customer feedback.

Webhook auto-close

My commit didn’t close the bug. Check:

1. The commit message contains a supported keyword exactly — see Auto-close via commit for the full keyword list (Fix, Fixes, Fixed, Close, Closes, Closed, Resolve, Resolves, Resolved). Both CP-<n> and #<n> formats are accepted.
2. The webhook is active in ClickProbe (Settings → Connect Git; the row should show a recent last_used_at).
3. GitHub/GitLab’s “Recent Deliveries” tab shows a 200 response to your push — if it shows 401, the secret mismatches; rotate in ClickProbe and re-paste into your repo settings.
4. If the response body says {"closed":[],"skipped":[{"bug_id":…, "reason":"not_found"}]}, the CP-<n> ID you referenced does not belong to the account that owns this webhook. Each webhook is scoped to one account.
5. If the response body says {"detail":"invalid signature"}, the secret stored in your repo settings doesn’t match the one ClickProbe has. Rotate the webhook secret in Settings → Connect Git and re-paste the new secret into GitHub/GitLab.

GitHub shows a red ❌ ping on webhook creation. This is expected — the receiver only handles push events and returns 422 for everything else (including the GitHub ping). The first real commit push will show a green ✅.

My bug reopened after a revert. Not currently supported — the webhook acts on forward commits only. Reopen the bug manually via the dashboard or use clickprobe.resolve_bug with status new.