MCP tools reference

Part of Sensefold for agents — the overview, setup guides, and permission tiers.

The Sensefold MCP server lives at https://api.sensefold.app/mcp. Connections authorize over OAuth (paste-and-authorize) or with a revocable Agent key, and carry one of three permission tiers. Write tools appear only when the connection’s tier allows them.

Tier	Can
read_only	Search and read the library
edit	Also save links and notes, update notes and tags
full	Also delete items (to the recycle bin — the user can restore)

See agent permissions for how tiers, OAuth connections, and Agent keys are managed, and privacy for agents for what a connected AI can see.

Tools

Tool	What it does	Tier
search_hub	Hybrid keyword + semantic search across the whole library; queries may be English, Chinese, or mixed. Prefer this for topic or meaning-based questions.	all
list_items	List recent items, newest first, with optional date range, provenance, and literal keyword filters.	all
get_item	Read one saved item by UUID — full content as Markdown-friendly text, served in windows or by matched section.	all
get_quota	Inspect the user’s plan, credits, and limits.	all
save_link	Save an HTTP(S) URL; it runs the normal capture + enrichment pipeline.	edit+
save_note	Save a plain-text or Markdown note. Notes are indexed but never AI-enriched.	edit+
update_note	Replace an item’s user-authored text. Revision-backed and undoable.	edit+
update_tags	Replace an item’s full tag list. Revision-backed and undoable.	edit+
delete_item	Move an item to the recycle bin; the user can restore it.	full

ChatGPT connectors additionally use the search and fetch aliases, which map onto the same search and read capabilities.

Connection self-check: your client’s tool list reflects the key’s tier — 6 tools for read-only (the four read tools plus the search/fetch aliases), 10 for edit, 11 for full.

What a search result carries

Every result from search_hub and list_items includes, alongside the title, summary, tags, and a body snippet:

• sensefoldUrl — the item’s address in the user’s library. This is the canonical link for referring to the item: when your AI cites what it used, this is the link to cite. Notes have one too, even though they have no source page.
• sourceUrl — where the material was originally captured from, if anywhere. Kept for attribution; it is not the citation link.
• chunkRef — when the match came from a specific section, a reference to it: the section’s ordinal and heading path, plus page numbers for PDFs. Pass the ordinal as get_item’s chunk parameter to read that section with its neighbours instead of the whole item. A chunkRef is ephemeral — editing the item invalidates it, so re-search rather than storing it.

The search and fetch aliases return the same links in their own field names (url, source_url).

Reading long items

get_item serves content in windows. The default window is the first 8,000 characters; when the response says truncated: true, call again with windowStart set to the response’s nextStart to continue (windows up to 20,000 characters). In chunk mode — chunk set from a search result’s chunkRef — the response reports which section ordinals were served.

Search degradation flags

A search_hub response also reports how it was ranked: rerankApplied: false means results are in approximate fusion order (the semantic reranker was skipped), and vectorSearchApplied: false means only keyword matching ran. In either case a rephrased query — different keywords, or the other language — helps most. Empty or weak results are worth one retry with a shorter query before concluding nothing exists.

Reliability contract

• For save_link and save_note, generate one UUID before the first attempt and reuse it on every retry — a new UUID creates a new item.
• update_note, update_tags, and delete_item require expectedVersion from a fresh get_item read. On a VERSION_CONFLICT error, re-read the item and retry once with the new version.
• Every write is versioned in Sensefold: the user can review, diff, and revert any agent edit from the item’s history. Write access never means giving up control.

Error codes and fixes (401, API_KEY_TIER_DENIED, VERSION_CONFLICT, ITEM_IDEMPOTENCY_MISMATCH, truncated reads) are in Troubleshooting. For a worked example of search_hub and get_item in a capture-to-citation research workflow, see the blog.

Reading never spends credits. save_note and update_note are free too; save_link spends credits exactly like a save from the extension, because it runs enrichment. See credits and billing.

An agent-readable setup guide lives at /for-agents/skill.md. Errors such as 401, VERSION_CONFLICT, API_KEY_TIER_DENIED, and ITEM_IDEMPOTENCY_MISMATCH are explained in troubleshooting. Back to Sensefold for agents.