MCP Troubleshooting

Most MCP problems fall into one of four buckets: the server never starts, no tools show up, every tool call is denied, or a single tool errors out. Work through them in that order.

Quick health check

Before digging in, run these on the machine that owns the daemon:


cmdop --version
cmdop agent status
cmdop mcp stdio --help
cmdop permissions audit --tail 10

If any of those fail, fix that first — the MCP server cannot work if the CLI cannot start, and tool calls cannot land if the daemon is not online.

Server never starts

Symptoms: Claude Desktop shows “MCP server failed to start”; Cursor’s tool list lacks the cmdop group entirely.

Likely causes, in order:

cmdop not on PATH. The MCP host launches its servers from a non-interactive shell. Run which cmdop from your interactive shell — if the path is /opt/homebrew/bin/cmdop or similar, hardcode it:
```
{
  "mcpServers": {
    "cmdop": {
      "command": "/opt/homebrew/bin/cmdop",
      "args": ["mcp", "stdio"]
    }
  }
}
```
Config JSON is invalid. A trailing comma or mismatched brace silently disables the entry. Lint the file (jq . claude_desktop_config.json or open it in an editor with JSON support).
The host is still running an old config. Quit Claude Desktop fully (not just close the window) and relaunch. In Cursor, run “MCP: Reload servers” from the command palette.

No tools listed

The server starts but the tool picker is empty.

Daemon not running. Run cmdop agent start and confirm with cmdop agent status that the verdict is ONLINE.
Daemon STARTING or DEGRADED. cmdop mcp stdio will respond but the agent’s tool catalog is incomplete. Wait for ONLINE, then restart the MCP host.
External MCP server failed to merge. Look for a registration error in cmdop agent logs -f — a third-party server that crashes on tools/list is silently skipped.

Every tool call is denied

Symptom: Claude or Cursor shows tool errors that look like “Permission denied” or “policy denied”.

This is the permission gate doing its job. MCP clients are remote callers — they always go through the gate.


cmdop permissions audit --tail 20

Look at decision, source, and reason:

`source`	What it means	Fix
`floor`	Hardcoded protection (`.env`, `.git`, `rm -rf /`, …)	You cannot override the floor. Change the request.
`rule`	A `deny` rule matched	`cmdop permissions revoke <rule_id>` if you wrote it.
`mode`	Mode is `strict` and no rule matched	Add a rule: `cmdop permissions allow '<tool>(<arg>)'`.
`ask_timeout`	Ask modal had no UI to answer	Open the desktop or the TUI, or add an explicit `allow`/`deny`.

A reasonable Claude Desktop policy on a server like vps-audi:


cmdop permissions mode strict
cmdop permissions allow 'read_file(/var/log/**)'
cmdop permissions allow 'execute_command(uptime)'
cmdop permissions allow 'execute_command(systemctl status *)'
cmdop permissions allow 'ask_agent(mac-studio)'

Single tool errors out

Pattern: most tools work, one returns garbage or a schema error.

Schema mismatch. Your MCP host caches tool schemas. Restart the host after a CMDOP upgrade.
Workspace mismatch. The daemon’s active workspace changed underneath the MCP server. Restart the host so it re-spawns cmdop mcp stdio with the new workspace.
External server tool. If the failing tool is namespaced (github:create_issue), the bug is in that server, not in CMDOP. Run the server standalone to see its stderr.

`ask_agent` / `ask_agents` failing

Cross-machine calls have their own error taxonomy. The result map distinguishes:

Class	Cause	First check
`resolve_error`	Unknown or ambiguous hostname	`cmdop connect --list` from the caller’s daemon.
`offline`	Target reports `is_online=false`	`cmdop agent status` on the target.
`dial_error`	Network or TLS failure	Caller’s `cmdop agent logs -f`.
`auth_error`	OAuth expired or no API key	`cmdop login` on the caller.
`remote_error`	Receiver itself failed	Target machine’s logs and audit log.
`timeout`	Per-host or total deadline fired	Tighten the prompt or raise `per_host_timeout_ms`.

See Agent Communication for the full taxonomy.

Updating CMDOP while MCP is wired up

The MCP host holds the cmdop binary open while a server is registered. Quit the host before cmdop update apply, then relaunch.

Last resort: start over

If state has drifted past easy debugging:


cmdop agent stop
cmdop agent start
# Then quit and relaunch Claude Desktop / Cursor

A clean daemon plus a clean host process clears most ghost states.