Reference

When something's wrong

The connection failures people actually hit, and what fixes each one.

Start here

Terminal
contextstream-mcp doctor

It checks each editor's configuration against what's actually on disk and reports what's missing. Most of what follows is something doctor will name first.

My assistant doesn't seem connected

In order:

  1. Restart the editor. Most read MCP configuration only at startup. This is the answer far more often than anything else.
  2. Check the file is where the editor expects it. Each one differs — see Set it up by hand.
  3. Check the binary is reachable. For local connections, GUI editors often don't inherit your shell's PATH. Use an absolute path in the config, or switch that editor to the hosted URL.

It's connected but never uses it

The most common cause is a missing or stale instruction file. Check the managed setup first:

Terminal
contextstream-mcp doctor

If it names the instruction layer, refresh that layer and restart the editor:

Terminal
contextstream-mcp update-rules

See Instruction files.

The connection exposes the capability; the managed instructions teach the assistant to take the initiative to ground, search, recall, and preserve context. Without that second half, you end up telling it what to retrieve on every turn.

It doesn't know anything about my project

Indexing hasn't finished. A large repository takes a few minutes on first connection. Ask again shortly.

Wrong project. Ask "what project am I in?" If that's wrong, the folder is bound to something else. Re-run the setup in the right folder.

The project is genuinely new. Memory starts empty. That's not a fault — it fills as you work.

Authentication fails

Terminal
contextstream-mcp verify-key

Confirms the credential directly. If it fails, generate a new key in the dashboard and update your config — or re-run the setup, which does both.

It worked yesterday and doesn't today

A managed refresh reported a warning. Run doctor, then repeat the specific config, instruction, or hook refresh it names. The normal contextstream-mcp update maintains all three for already configured editors.

The key was revoked. verify-key will say so.

The editor updated and moved its config. doctor compares against the current locations.

Lookups are slow

The hosted connection uses the fast context mode by default (?default_context_mode=fast in the URL). If yours lacks that parameter, add it — the deeper mode costs latency you'll feel in an editor.

Nothing here matches

contextstream-mcp doctor --json is the useful diagnostic to attach to a report. It does not include source-file contents, but it can include editor names, configuration paths, scope/readiness metadata, and failure details. Inspect it before sharing outside your organization.

Next