Troubleshooting & Gotchas
Known issues and how to fix them.
Gotcha 1: Made-up projectPublicId
Passing a fabricated
Passing a fabricated
projectPublicIdreturns a clean backend error: "Project not found". Projects must be created in the thorbit.ai web app. The MCP has no create-project tool.Gotcha 2: KB vs Pipeline layer
The 9 KB tools in
The 9 KB tools in
thorbit-kb-mcp are self-sufficient — no project needed. The 18 pipeline and on-page tools in thorbit-content-mcp all require a projectPublicId. Only the 3 scraper tools (extract_url, harvest_serp, reddit_research) are standalone.Gotcha 3: No delete tool
Neither server has a delete tool. To remove a knowledge base or content piece, use the thorbit.ai web app. Ingestion is also append-only in V1 — refresh is disabled.
Neither server has a delete tool. To remove a knowledge base or content piece, use the thorbit.ai web app. Ingestion is also append-only in V1 — refresh is disabled.
Gotcha 4: Cold start latency
A new key over npx can take 5–10 seconds before the first handshake responds. This is normal. Wait for "Connected" status before sending tool calls.
A new key over npx can take 5–10 seconds before the first handshake responds. This is normal. Wait for "Connected" status before sending tool calls.
Quick Diagnostics
| Symptom | Cause | Fix |
|---|---|---|
| Project not found error | Invalid or missing projectPublicId | Create project at thorbit.ai web app, copy the real ID |
| Server not appearing as Connected | Cold start or client not restarted | Wait 10s, restart client, run claude mcp list |
| KB search returns empty | Ingestion not complete or wrong KB ID | Check source status with thorbit_kb_source_status |
| Pipeline tools fail without clear error | Missing projectPublicId — KB tools mask this | Confirm you are using a content pipeline tool, not a KB tool — add projectPublicId |
| Old content persists after re-ingestion | Ingestion is append-only in V1 | Delete KB via web app, recreate, re-ingest |