Cookbook: Deep Research over MCP

Updated October 15, 2026

Search returns passages. For research, an agent usually needs to find the right publications and then read the relevant sections in full. The Cashmere MCP server has three tools for this, used in order:

find_relevant_sources -> get_table_of_contents (optional) -> get_section

The second half of this page gives the same steps as REST calls, for agents that don't use MCP.

To connect an MCP client, see Connecting MCP to Claude or Connecting MCP to ChatGPT.

Over MCP

1. find_relevant_sources

Searches, then keeps the single best passage per publication, so you get a list of distinct sources rather than ten passages from the same book.

Argument Notes
query Required
collection_id One collection ID
limit Number of distinct sources, default 10
published_after, published_before YYYY-MM-DD

Each source has omnipub_uuid, omnipub_title, omnipub_publisher, omnipub_published_at, relevance_excerpt, score, section_label and section_block_uuid.

2. get_table_of_contents (optional)

Use it when the agent needs a section other than the one search found, such as the chapter after it or the methods section.

Argument Notes
publication_id The omnipub_uuid
page, page_size Pages through the table of contents. page_size defaults to 200, max 1000. Check has_next.

Each nav entry has order, level, label and section_block_uuid. Entries with no section_block_uuid are headings with no body text of their own.

3. get_section

Argument Notes
publication_id The omnipub_uuid
section_block_uuid From step 1 or 2. Takes priority over section_order.
section_order An order from step 2
page Page within a long section, default 1

The response has section.text, section.total_pages, next and prev cursors ({section_order, page}), and a view_source_url for citing the page. Follow next to keep reading. At the end of a section it moves on to the next section.

Skip step 2 when the section search found is enough. Pass its section_block_uuid straight to get_section.

If one of these tools is missing from your client, check the key's Allowed Endpoints. The MCP server hides any tool whose endpoint the key can't reach: find_relevant_sources needs Search, and the other two need Omnipub.

Over REST

The MCP tools call these endpoints.

curl "https://cashmere.io/api/v2/search?q=sepsis+early+antibiotics&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

There's no per-publication deduplication in REST. find_relevant_sources requests about five times as many results as it needs, then keeps the highest-score result per omnipub_uuid. Do the same if you want distinct sources. Keep omnipub_uuid and section_block_uuid from each result you keep.

2. Table of contents: GET /omnipub/{uuid}

curl "https://cashmere.io/api/v2/omnipub/OMNIPUB_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

The table of contents is data.nav, a list of {order, level, label, section_block_uuid}. The response also has data.title, token_count and word_count. REST doesn't page nav; the whole list comes back.

3. Read a section: GET /omnipub/{uuid}/content

curl "https://cashmere.io/api/v2/omnipub/OMNIPUB_UUID/content?section_block_uuid=SECTION_BLOCK_UUID&fields=view_source_url" \
  -H "Authorization: Bearer YOUR_API_KEY"
Parameter Notes
section_block_uuid Opens the section with this UUID. Takes priority over section_order.
section_order Opens the section at this order. If that entry is a heading with no body text, it opens the next section that has some.
page Page within the section, default 1
fields=view_source_url Adds a tracked citation link. Off by default.

With neither section parameter, it opens the first section that has content.

{
  "omnipub_uuid": "...",
  "omnipub_title": "...",
  "total_sections": 42,
  "section": {
    "section_order": 7,
    "section_label": "Early Management",
    "text": "...",
    "token_count": 1830,
    "page": 1,
    "total_pages": 2,
    "view_source_url": "https://..."
  },
  "next": {"section_order": 7, "page": 2},
  "prev": {"section_order": 6, "page": 1}
}

To keep reading, pass next.section_order and next.page back as section_order and page. next is null at the end of the publication.

fields is a list parameter. Repeat it for each field (fields=view_source_url&fields=other).

Costs and citations

  • Every section page you read counts toward token usage, as do the search and the table-of-contents call. Read the sections the agent needs, not the whole publication.
  • Each view_source_url is minted fresh per request. Use it unmodified, and don't cache it. It differs from a search link in one way: the access token is signed when you make the request, so the 24-hour window starts then, not at the first click. Fetch the section again when you need a fresh link. More on citation links: RAG with Citations.

See also