Troubleshooting

The tool count does not match

A connection’s tool list reflects its tier: 6 tools for read-only (search_hub, list_items, get_item, get_quota, search, fetch), 10 for edit, 11 for full. If write tools are missing, the key or connection is read-only — that is the OAuth default. A tier cannot be changed in place: create a new key with the tier you need, or reconnect and pick it during authorization. Then restart the client so it re-reads tools/list.

401 “Invalid Agent API key” or “Agent API key required”

• The header must be exactly Authorization: Bearer lexi_agent_v1_production_…. Check for a missing Bearer , stray quotes, whitespace, or a key cut off when pasting — the full key is long.
• The key was revoked. Keys are shown once; if it is gone, create a new one under Settings → For agents.
• If you set the key in an environment variable, the client was started before the variable existed. Restart it.
• On the MCP endpoint the same failure appears as JSON-RPC error -32001 “Agent API key required”.

403 API_KEY_TIER_DENIED

The call is outside the key’s tier (for example delete_item on an edit key). See Permissions.

The client keeps asking me to authorize

Reconnecting the same OAuth client revokes its previous connection, so adding the connector twice — or in two places — leaves only the newest one working. Remove the Sensefold connector from the client, check Settings → For agents for a single active row (revoke stale ones), then add it once and finish the authorization in the browser before returning to the client.

The OAuth callback page did not load

CLI agents finish authorization on a 127.0.0.1 callback. When the browser runs elsewhere than the agent, that page cannot load — expected, not an error. OpenClaw accepts the code from the address bar via --code; Hermes has a remote-gateway helper. If the client offers no such path, use an Agent key instead.

ChatGPT has no Developer mode

Developer mode is what exposes remote MCP in ChatGPT and its availability depends on your account and workspace policy. If it is not offered, Sensefold cannot enable it from its side.

Search returns nothing

• Libraries are often bilingual: retry in the other language or with different keywords. The tool description tells the model to do this on its own.
• Just saved? Items become searchable after enrichment finishes, usually within moments.
• At zero credits, new captures wait as pending and are not indexed until you process them — see Credits and plans.

A long item is cut off

get_item serves content in windows: the first 8,000 characters by default, up to 20,000 per call. When the response has truncated: true, call again with windowStart set to the response’s nextStart. ChatGPT’s fetch alias continues through metadata.next_id. Well-behaved clients do this without being asked.

VERSION_CONFLICT

The item changed since the version your agent passed as expectedVersion. Re-read with get_item and retry once with the new version. This is the guard that keeps two writers from overwriting each other.

ITEM_IDEMPOTENCY_MISMATCH

save_note was called with an id that already exists but different content. Ids are for safe retries of the same content; to change an existing note, use update_note.

Why did enrichment not run?

A capture with no summary or tags has usually hit one of two things:

• No credits. The save succeeded as a pending capture. get_quota shows credits.total: 0; buy a credit pack or wait for the monthly reset, then use Process now in the web app.
• AI consent not granted. Save results report consentRequired: true. Grant consent in the web app Settings.

The extension does not show the page as saved

• The side panel checks the page address against your library only after you have accepted the extension’s page-access disclosure, and only while the panel is open.
• Highlights come back only on sites where the highlighter is switched on.
• The page URL must match what was saved: a different query string or a tracking parameter can make it a different page.
• Saving again cannot create a duplicate — Re-capture refreshes the preview card. If you see “Already saved; edits were not applied”, the item already existed; make your edits in the web app instead.

Still stuck? Check the MCP tools reference or write to hello@sensefold.app.