Skip to main content

​
The new tool doesn’t show up

  • Restart your AI tool (Claude Desktop / Cursor / Antigravity).
  • Start a new chat after restart.
Many clients cache the MCP tools/list result for a connection or chat. Write tools remain visible with mcp:read, but invoking one requires a compatible client to complete an mcp:write step-up.

​
Write access is granted, but saving still asks for confirmation

The server checks confirmation for the exact tool arguments separately from OAuth write scope. Complete the host’s confirmation exchange. If the host cannot handle that exchange, writes are not supported by that connection; use Capsulate to apply the reviewed change.

​
Contribution tools are missing

Check server deployment as well as the cached tool list. The tools are added in PR #1616, and their database migration must be present. Reconnecting alone cannot enable tools that have not been deployed.

​
A finding fails because the record or schema changed

Read records_schema, record_get, and finding_context again. Review the new facts and submit a fresh finding with a new request ID. Keep the same ID and identical input only for retries of the original submission. Do not silently substitute a new value into a previously reviewed save.

​
The save response was lost

Use finding_get with the original request_id as contribution_id. If it is still a draft, review and apply that saved contribution. If already applied, inspect its receipt and use record_get for the current cell value. Follow nextBefore and nextBeforeId together when paging findings_list.

​
Research finished, but the cell is blank

For external findings, check evidenceSaved and valueApplied: uncertain or not_found outcomes save evidence only. For Capsulate research, inspect fresh research_records or research_task save outcomes. research_enqueue can retry saving an existing supported finding; research_refresh performs research again and requires its own reusable UUID v4 request ID. Cancelling a job does not undo a saved value.

​
Remote MCP returns auth or billing errors

  • Re-run the MCP client login flow so it can refresh the OAuth session.
  • Verify the account has access to the app.
  • Retry server_diagnostics first to confirm the connection state.

​
“Tool execution failed” or “API error”

  • Narrow the request and try again.
  • Re-run server_diagnostics.
  • Confirm the configured URL is https://capsulate.app/mcp.
  • Prefer canvases_list, patterns_list, or records_find over broad search calls when you are just trying to inventory data.

​
A large tool result looks truncated

That is expected for oversized MCP payloads. Fix:
  • narrow the query
  • reduce limit
  • fetch only the records you need
  • use bulk_fetch on a selected id list instead of a broad search result

​
An older initialization-based connection stops working after a restart

That can happen if a deployment or process restart interrupts an active session. Fix:
  • reconnect the server or start a new client session
  • prefer the current MCP 2026 connection flow when your client supports it