Troubleshooting

If something's not working, start here. Most problems fall into one of three buckets.

Connection issues

Claude Desktop doesn't show Debriefer in its MCP list

Claude Desktop silently swallows JSON parse errors in the config file. Check your file at ~/Library/Application Support/Claude/claude_desktop_config.json (or the Windows/Linux equivalent) with python -m json.tool <file> to validate. Fully quit and relaunch Claude Desktop — not just close the window.

Cursor doesn't see the server

Cursor reads .cursor/mcp.json from the project root, not your home directory. Make sure the file is in the project you're currently working in. After editing, reload the window (Cmd/Ctrl+Shift+P → "Reload Window").

npx @debriefer/mcp-server is slow on first start

The first launch downloads the package. Subsequent launches are instant. If it hangs, run npx @debriefer/mcp-server --help from a terminal to pre-cache it.

The HTTP server connects but no tools appear

Check the initialize response — if capabilities.tools is empty, the client never asked for tools. Make sure your client sends capabilities: { tools: {} } on initialize.

Authentication issues

Every tool call returns 401 Unauthorized

Three things to check:

1. The API key is a real Debriefer key, not a placeholder. Keys start with sk_live_ or sk_test_.
2. In HTTP mode, the header is Authorization: Bearer <key> — not Api-Key:, not X-Api-Key:.
3. The key hasn't been revoked. Check app.debriefer.ai → Settings → API keys.

I rotated my key and now nothing works

Update the key in your client's config file, then fully restart the client. Env vars are read once at startup; a simple reload may not refresh them.

403 Forbidden on a tool I expect to work

The key is valid but scoped to a different organization. Check that the key belongs to the organization that owns the blueprint or run you're trying to access.

Tool-call issues

validate_graph says my graph is invalid

Read the error payload — it contains a list of specific issues (unreachable_node, missing_start, cycle_detected). Each points to a node or edge ID. Fix the flagged item and revalidate.

create_interview_run returns blueprint_not_published

Runs can only be created from published blueprints. Call publish_blueprint first, or use scaffold_interview which publishes in the same call.

My assistant keeps making up node IDs

Load the blueprint as a resource first (debriefer://blueprints/{id}) — then the assistant refers to the real node IDs instead of inventing them. See Resources.

get_analysis returns analysis_not_ready

Analysis runs asynchronously after an interview completes. Either poll the endpoint, wait for the webhook, or call trigger_analysis to force a fresh run.

Still stuck?

Check the MCP server source or open an issue against the repo. Include: your client, transport (stdio / HTTP), server version (debriefer-mcp --version), and the full error payload.