Errors

All Nexus-Catalyst MCP tools return a consistent error shape on failure:

{
  "error": true,
  "message": "Descriptive error message",
  "code": "ERROR_CODE",
  "suggestion": "How to fix the issue"
}

Non-error responses may still carry disambiguation_required: true (Linear multi-workspace) — that is not a failure; pass the workspace label and retry.

Authentication (401)

Symptom	Likely cause	Fix
Tool calls fail with 401	OAuth session expired	Re-authenticate from your client’s MCP settings
Claude Code plugin errors	NC_PLUGIN_API_KEY missing or revoked	Regenerate key in dashboard; export in shell profile
Works in one client, not another	Per-client OAuth	Sign in separately in each client

Writes blocked

Symptom	Likely cause	Fix
store_context rejected	Subscription lapsed	Resume billing in dashboard
update_user_facts rejected	Document over ~4 KB	Prune stale paths; see User facts

Recall empty

Symptom	Likely cause	Fix
recall_context returns nothing	No matching memories yet	Store one first; use specific queries
Wrong memories surface	Vague query	Name the subject; pass full user_query_full
Expected project memory missing	Wrong client_project on store	Tag stores with repo slug; see Scoping

Linear integration

Symptom	Likely cause	Fix
disambiguation_required	Multiple workspaces configured	Pass workspace label from the response
Unknown filter key error	Typo in search_filters	Use only documented keys — unknown keys fail loudly by design
Truncated counts	limit too low	Raise limit or narrow filters when may_be_truncated: true

Invalid memory IDs

• Use standard UUID memory IDs from recall_context / search_memories
• vs-result-* IDs are legacy vector-store artifacts — unreliable for get_memory_detail

Client-specific

Detailed connection and hook failures → Common Issues.

Tool parameter reference → MCP tools.