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 your 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. Optional `setId` limits results to one share page.	all
`list_items`	List recent items, newest first, with optional date range, provenance, literal keyword, and share-page (`setId`) 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
`list_share_pages`	List the user’s share pages with title, item count, and state (`active`, `paused`, or `blocked`). Pass a page’s `id` as `setId`, or to `fetch`.	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 for search; they are never summarized automatically.	edit+
`update_note`	Replace an item’s user-authored text. Revision-backed and undoable.	edit+
`update_tags`	Replace the user’s own tags on an item (the full list). AI tags are not affected. 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. search also takes setId, and fetch also accepts a share page’s id: it returns the page’s current item titles, their ids in metadata.itemIds, and the page’s public address without its secret part.

Agents can read share pages but cannot create, change, pause, or delete them; that stays with the user in the Sensefold app.

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

What a search result carries

Every result from search_hub and list_items includes, alongside the title, summary, the user’s own tags, and a body snippet (AI tags are not exposed to agents):

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.