MCP troubleshooting¶

When MCP setup, tool calls, or change-control responses fail — start here. Install and transport basics: Client setup, Server & transport.

Install and launcher¶

Symptom	Fix
`CodeClone MCP support requires the optional 'mcp' extra`	`uv tool install "codeclone[mcp]"` or `pip install 'codeclone[mcp]'`
Client cannot find `codeclone-mcp`	Install the extra above, or point `command` at the full launcher path in MCP config
Wrong / missing tools after upgrade	Restart the MCP process; confirm `codeclone --version` matches the client bundle
Plugin installed but MCP silent	Check client MCP logs; verify stdio command is `codeclone-mcp --transport stdio`

Symptom	Fix
HTTP server refuses to start	Set `CODECLONE_MCP_AUTH_TOKEN` to ≥32 characters before launch — no unauthenticated HTTP
Remote client cannot connect	Use `streamable-http`; pass Bearer token; for non-loopback hosts add `--allow-remote`
Client only accepts remote MCP	See Server & transport — stdio for local IDEs

Symptom	Fix
`requires an absolute repository root`	Pass full path (`/Users/.../repo`), not `.` or a relative segment
`Repository root '…' does not exist`	Fix typo; ensure the path is the repo root on the machine running MCP
`path traversal not allowed`	Use repo-relative paths inside tools; do not pass `../` escapes
`changed_paths` rejected	Pass `list[str]` of repo-relative file paths, or use `git_diff_ref`
`analyze_changed_paths` fails	Provide either `changed_paths` or `git_diff_ref`, not neither
`cache_policy='refresh' is CLI-only`	MCP accepts `reuse` (default) or `off` only
`coverage_xml requires analysis_mode='full'`	Set `analysis_mode="full"` before joining Cobertura XML
Stale or wrong findings	Call `analyze_repository` again; runs are in-memory and bounded (`--history-limit`)

Symptom	Fix
Agent reads results from an old run	Re-analyze, or pass the explicit `run_id` you intend
Review markers out of sync	`mark_finding_reviewed` + `list_findings(exclude_reviewed=true)`; markers are session-local
Need a clean MCP session	`clear_session_runs` — also clears workspace intents; see Session markers
Process restarted — intents gone	Expected: intent registry is ephemeral; re-run `analyze_repository` → `start_controlled_change`

`status` / message	What to do
`needs_analysis`	Call `analyze_repository(root=<abs>)` before `start_controlled_change`
`queued`, `edit_allowed: false`	Another intent is active — `manage_change_intent(action="promote")` or narrow scope
`blocked`, dirty scope overlap	Inspect git diff; commit/stash/revert, narrow scope, or `dirty_scope_policy="continue_own_wip"` for own WIP
`finish` → `unverified`	Follow `next_step` in the response (often a new after-run + same `intent_id`)
`finish` → `violated`	Fix scope or regressions; or `start` again with expanded `allowed_files`
Foreign intent overlap	Coordinate with the user — do not kill foreign PIDs without confirmation

Full workflow: Change control.

Symptom	Fix
`get_relevant_memory` fails without `root`	Always pass the same absolute `root` as analysis — `intent_id` alone is invalid
Empty memory on first use	Normal — `bootstrap_if_missing` ingests on first scoped call after `analyze_repository`
Cannot approve drafts via MCP	By design — use VS Code Memory view; agents only `record_candidate`

codeclone --version and codeclone-mcp --help succeed on the host that runs MCP.
root is absolute and points at the repository the client has open.
analyze_repository → get_run_summary works before deeper tools.
help(topic="engineering_memory") or help(topic="change_control") for contract copy.
Enable server debug: codeclone-mcp --log-level DEBUG (stdio clients: check MCP stderr).

If the steps above do not match what you see, open a GitHub issue:

Include: