MCP tool reference

The hosted MCP server at https://api.smry.ai/mcp advertises 28 tools to an authenticated caller. This page lists every one of them with its purpose and its REST equivalent, so you can move between the two transports without guessing. Setup lives in Connect an agent.

Which tool should I call

The job	Call	Not
Read a link	`get_article` — a token-budgeted window plus `next_cursor`	Not `open_web_pages`, which is for pages you found through `search_web`
Answer a question about a link	`search_article` — only the passages that match, with anchors	Not `get_article` then reading it all. `search_article` costs roughly a tenth as much.
Find something already saved	`list_library_objects` — items, notes, and highlights in one corpus	Not `list_library`, unless you need lifecycle filters or `view=history`

The order that wastes the least context is: search the account first, search the page second, read the page third, take the whole text never.

Call a tool

A tool call is a JSON-RPC tools/call request to the same endpoint.

curl https://api.smry.ai/mcp \
  --header "Authorization: Bearer $SMRY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_article",
      "arguments": {
        "url": "https://www.nasa.gov/news-release/nasa-sets-coverage-for-agency-crew-mission/",
        "query": "when does the launch window open",
        "max_passages": 5
      }
    }
  }'

import httpx

response = httpx.post(
    MCP_URL,
    headers={
        "Authorization": f"Bearer {SMRY_API_KEY}",
        "Accept": "application/json, text/event-stream",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "search_article",
            "arguments": {
                "url": "https://www.nasa.gov/news-release/nasa-sets-coverage-for-agency-crew-mission/",
                "query": "when does the launch window open",
                "max_passages": 5,
            },
        },
    },
).raise_for_status().json()

for passage in response["result"]["structuredContent"]["passages"]:
    print(f"¶{passage['anchor']}  {passage['text']}")

const response = await fetch(MCP_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMRY_API_KEY}`,
    "Content-Type": "application/json",
    Accept: "application/json, text/event-stream",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "search_article",
      arguments: {
        url: "https://www.nasa.gov/news-release/nasa-sets-coverage-for-agency-crew-mission/",
        query: "when does the launch window open",
        max_passages: 5,
      },
    },
  }),
});

const { result } = await response.json();
for (const passage of result.structuredContent.passages) {
  console.log(`¶${passage.anchor}`, passage.text);
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "5 passages matched \"when does the launch window open\"." }
    ],
    "structuredContent": {
      "source_url": "https://www.nasa.gov/news-release/...",
      "reader_url": "https://smry.ai/...",
      "title": "NASA Sets Coverage for Agency Crew Mission",
      "publisher": "NASA",
      "published_at": "2026-08-14T15:02:00.000Z",
      "extraction_source": "pulpie",
      "cache_hit": true,
      "total_blocks": 41,
      "total_tokens": 5820,
      "query": "when does the launch window open",
      "matched_blocks": 5,
      "tokens_returned": 388,
      "next_cursor": null,
      "passages": [
        {
          "anchor": 12,
          "section": "Mission timeline",
          "rank": 1,
          "score": 0.82,
          "tokens": 74,
          "text": "The launch window opens at 4:21 p.m. EDT on Thursday..."
        }
      ]
    }
  }
}

Read structuredContent. For every tool except get_article and search_article, content[0].text is a one-line summary, kept short on purpose so a long response is not serialized into your context twice. Those two repeat the article window or the matched passages in content[0].text, so their response arrives in your context twice — budget for it.

Tool arguments are snake_case, with three exceptions. set_feed_feedback takes entryId, and manage_feed_filter takes previewToken and expectedRevision. Those three names are inherited from REST. Send them as written — normalizing them to snake_case is a schema error.

Outputs follow their family: article and feed tools return next_cursor, library tools return nextCursor. Over HTTP the split is different again — article and library operations are camelCase, feed operations are snake_case. Echo whichever key you were given.

search_saved_item is the one library tool that returns snake_case. Its response carries next_cursor, content_kind, total_blocks, matched_blocks, and tokens_returned. Read nextCursor from it and you read undefined, so the loop stops silently after one page.

Articles

Both tools are public: they read a URL the caller supplies and never touch an account. Details in Read a URL.

Tool	Purpose	REST equivalent
`get_article`	Read a public article or YouTube URL as a token-budgeted window with paragraph anchors and a continuation cursor.	`POST /v1/articles/read`
`search_article`	Return only the passages of one URL that answer a query, each anchored and labelled with its section.	`POST /v1/articles/search`

Library

Every library tool is account-scoped. Details in Work with the library.

Tool	Purpose	REST equivalent
`list_library_objects`	Search saved items, standalone notes, and highlights as one corpus. Returns stable refs.	`GET /v1/library/objects`
`get_library_object`	Read one object by the ref `list_library_objects` returned.	`GET /v1/library/objects/{ref}`
`list_library`	Search and filter saved items by tag, kind, status, or date; `view=history` returns reading history.	`GET /v1/library/items`
`get_saved_article`	Read one saved item plus a token-budgeted window of its stored text.	`GET /v1/library/items/{id}` and `GET /v1/library/items/{id}/content`
`search_saved_item`	Return only the stored passages of one saved item that answer a query.	`POST /v1/library/items/{id}/search`
`get_library_asset`	Return an authenticated `smry://` resource link for an item’s original file; `include_data` shows images and audio inline.	`GET /v1/library/items/{id}/asset`
`get_library_changes`	Replay every library mutation and deletion since a cursor.	`GET /v1/library/changes`
`save_article`	Extract a public URL and save it. Idempotent per URL; reports hard paywalls instead of claiming success.	`POST /v1/library/items`
`save_content`	Save text or a document you already hold, without fetching a URL.	`POST /v1/library/items`
`update_library_item`	Move, tag, star, mark read, set progress, or correct the classification of one item.	`PATCH /v1/library/items/{id}`
`bulk_update_library_items`	Apply the same changes to up to 100 items atomically.	`PATCH /v1/library/items`
`remove_library_item`	Delete one saved item. Uploaded originals are permanently deleted; highlights and notes are kept.	`DELETE /v1/library/items/{id}`

list_library accepts include_counts: true, which folds in the same numbers as GET /v1/library/counts. There is no separate counts tool.

Feeds

Details in Follow sources.

Tool	Purpose	REST equivalent
`query_feeds`	Read followed feeds: entries, per-source health, or grouped aggregates. `{"since":"1d"}` is the catch-up call.	`POST /v1/feeds/query`
`get_feed_changes`	The polling primitive: what changed since a cursor, or since a managed consumer’s checkpoint.	`POST /v1/feeds/changes`
`follow_feeds`	Follow up to 20 feed or site URLs in one call, with a per-URL outcome for each.	`POST /v1/feeds/follow`
`discover_feed_inputs`	Compact discovery adapter: find feeds by topic, or list the feeds a site publishes.	`POST /v1/feeds/search`
`search_feeds`	The full discovery catalog behind smry’s Discover page, with language, source-type, and popularity controls.	MCP only
`create_news_query`	Create a durable keyword news source that behaves like any followed feed.	`POST /v1/feeds/inputs/news-query`
`set_feed_feedback`	Record or undo “less like this” on one entry.	`POST /v1/feeds/feedback`
`mutate_feeds`	Selector-based writes — unfollow, move, rename, mark read or unread — with a dry-run preview and a commit token.	`POST /v1/feeds/mutate`

Discovery never subscribes. Pass the feedUrl values that search_feeds or discover_feed_inputs returned to follow_feeds.

Collections

Collections are the folders that hold feed inputs. Two tools cover them, each with an action discriminator.

`manage_collections`

`action`	Does	REST equivalent
`list`	List Collections with their IDs, names, and filter state.	`GET /v1/feeds/collections`
`create`	Create a Collection, optionally with starting members.	`POST /v1/feeds/collections`
`update`	Rename a Collection or replace its membership. Membership is a complete replacement.	`POST /v1/feeds/collections/{id}`
`delete`	Delete a custom Collection; its inputs move to Unsorted.	`DELETE /v1/feeds/collections/{id}`

`manage_feed_filter`

`action`	Does	REST equivalent
`preview`	Classify a bounded recent sample against a plain-English filter and return a `previewToken`, counts, samples, and coverage.	`POST /v1/feeds/filters/preview`
`apply`	Apply that exact preview, guarded by `expectedRevision`. A preview created with `filter: null` clears the filter.	`POST /v1/feeds/filters/apply`

Consumers

`manage_feed_consumers`

A consumer is a saved where predicate plus one checkpoint that smry retains for you. Use one per independent processing loop, not per source. The full loop is in Managed consumers.

`action`	Does	REST equivalent
`create`	Save a named predicate. New consumers start at the current high-water mark.	`POST /v1/feeds/consumers`
`list`	List consumers, their acknowledged cursors, and how many entries are waiting.	`GET /v1/feeds/consumers`
`ack`	Acknowledge the `next_cursor` from the batch you finished processing.	`POST /v1/feeds/consumers/{id}/ack`
`delete`	Remove the predicate and checkpoint. Followed sources and read state are untouched.	`DELETE /v1/feeds/consumers/{id}`

A managed batch repeats until its next_cursor is acknowledged. Skip the ack and you will process the same entries forever.

Monitors

Tool	Purpose	REST equivalent
`create_monitor`	Watch a page or sitemap on a schedule; detected changes arrive as an ordinary followed source.	`POST /v1/feeds/monitors`

Monitors are queried, watched, and mutated with the feed tools above. Active monitor limits are 3 on Free, 10 on Patron, and 100 on Pro. The shortest interval is 60 minutes. Details in Watch a page for changes.

Web

Both tools are MCP only. Nothing in the HTTP API searches the open web.

Tool	Purpose	REST equivalent
`search_web`	Run up to four focused public-web searches and return ranked snippets.	MCP only
`open_web_pages`	Open up to four public pages and return clean Markdown, optionally narrowed to a stated context.	MCP only

Snippets are discovery aids. Open the strongest results before citing a substantive claim.

HTTP operations with no tool

Five operations are reachable only over HTTP, on purpose.

Operation	Why there is no tool
`POST /v1/feeds/export`	Returns up to 10,000 NDJSON rows. That belongs in a file and local compute, never in a context window.
`POST /v1/articles/extract`	Returns the complete article text in one response. `search_article` or `get_article` answers the same question for a fraction of the tokens.
`GET /v1/me`	Account capabilities and limits. A tool does not need to read its own quota; handle the `429` instead.
`PUT /v1/library/items/{id}/asset`	Uploads raw file bytes up to 100 MB. Binary bodies do not belong in JSON-RPC.
`GET /v1/library/counts`	Folded into `list_library` as `include_counts`.

Common mistakes

Operations models invent, and what to call instead.

Connect an agent

Install, authenticate, and verify the server.

Get connected

Agent workflows

Recipes

Reference

MCP tool reference

Which tool should I call

Call a tool

Articles

Library

Feeds

Collections

`manage_collections`

`manage_feed_filter`

Consumers

`manage_feed_consumers`

Monitors

Web

HTTP operations with no tool

Next

Common mistakes

Connect an agent

​Which tool should I call

​Call a tool

​Articles

​Library

​Feeds

​Collections

​manage_collections

​manage_feed_filter

​Consumers

​manage_feed_consumers

​Monitors

​Web

​HTTP operations with no tool

​Next

Common mistakes

Connect an agent

Which tool should I call

Call a tool

Articles

Library

Feeds

Collections

`manage_collections`

`manage_feed_filter`

Consumers

`manage_feed_consumers`

Monitors

Web

HTTP operations with no tool

Next