Troubleshooting

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

Connection issues

The connector won't add, or the URL is rejected

Make sure you pasted the full endpoint, including /mcp: https://mcp.debriefer.ai/mcp (or https://mcp.debriefer.dev/mcp for staging). The client connects over HTTPS, so a bare hostname or an http:// URL won't work.

Claude doesn't show Debriefer in its connectors

Open Settings → Connectors and confirm Debriefer is listed and marked connected. If it's there but greyed out, the OAuth session likely expired - remove the connector and add it again to re-authorise. Then start a new chat so Claude reloads the tool list.

Adding the connector should pop a browser window to authorise Debriefer. If it doesn't:

Check your pop-up blocker - allow pop-ups for the assistant.
If the window opens but errors, make sure you're signed in to the same Debriefer account you intend to use.
Try removing and re-adding the connector to restart the flow cleanly.

It connects but no tools appear

Start a new chat after authorising - most clients only load a connector's tools at the start of a conversation. If tools still don't show, remove and re-add the connector.

Authentication issues

The connection returns `401 Unauthorized`

A 401 means the assistant has no valid token yet - the OAuth sign-in didn't complete. Remove the connector and add it again; when the browser window opens, sign in and approve access. There are no API keys to set - if you're trying to paste a key, you're on the wrong flow.

My session stopped working after a while

Tokens refresh automatically, but if you revoked access (or it's been a long time), the assistant may need to re-authorise. Remove and re-add the connector to sign in again.

`403 Forbidden` on a tool I expect to work

You're authorised, but the resource belongs to a different organisation than the one you signed in with. Confirm you authorised with the Debriefer account that owns the blueprint or run you're trying to reach. To switch organisations, re-authorise with the right account.

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?

Open an issue or get in touch. Include: which client you're using, whether you're on production (mcp.debriefer.ai) or staging (mcp.debriefer.dev), and the full error message. If you've connected Debriefer to a client we don't list yet, tell us - we'd love to add it.

On this page