The three tools the Expand MCP server gives an agent, with every parameter, default, and result field, plus the two documentation resources.
The Expand MCP server gives an agent three tools. fetch is a Fetch in JSON Mode. get_snapshot reads a public Snapshot catalog, or returns Snapshot Highlights when given a highlights object. fetch_appendix reads the Appendix of a page the agent already fetched. Fetch and Highlights results carry a ready-made citation block. Two documentation resources point the agent at the setup guide.
The server runs in two places, with the same tools either way.
Hosted
https://api.expand.ai/v1/mcp
Streamable HTTP, nothing installed. The agent signs in through the browser with OAuth, or sends an Expand API key as . The per-client setup is on .
Agents launch this command from their MCP config, not from a terminal. It uses the credentials from expandai login, so no key is written into the config. expandai init or expandai mcp install <host> <scope> writes the entry for you. For Claude Code and Cursor it looks like this:
Read a public Snapshot catalog by snapshotId, or add highlights for relevant passages. No new Fetch.
fetch
Calls POST /v1/fetch/json and returns the JSON object. The agent's tool description tells it to use fetch before curl or a built-in web-fetch tool on any public page, and to skip it for localhost, private hosts, and JSON APIs.
Option
Definition
Default
url
The page to fetch.
Required
highlights
A highlights object. When set, the result also carries Fetch Highlights under data.highlights.snippets.
None
The highlights object:
Option
Definition
Default
query
The query.
Required
maxResults
Most snippets to return, 1 to 50.
5
Note
minScore defaults to 0 here and to 0.6 in the CLI, the TypeScript SDK, and the API. An agent sees every snippet up to maxResults unless it raises the score. How to tune both is on Two ways to highlight.
The Snapshot. meta.snapshotId is the ID to pass to get_snapshot and fetch_appendix. meta.playground is the capture link.
markdown
The Main Markdown, with the citationBlock appended after a --- rule.
When the origin never answered, the tool returns an error that names the failure and whether a retry makes sense, instead of content. See Errors & retries.
get_snapshot
Without highlights, returns the public catalog with collections, artifacts, and links. No authentication is needed.
With highlights, calls POST /v1/snapshots/<snapshotId>/highlights and returns Snapshot Highlights for a page the agent already fetched. The page is not fetched again. Highlights requires authentication and costs one Highlights credit.
Option
Definition
Default
snapshotId
meta.snapshotId from an earlier fetch result.
Required
highlights
The same highlights object as fetch: query, maxResults, .
The layer options apply when highlights is present. Turning all three layers off returns 400 BadRequest.
Warning
Pass meta.snapshotId, the capture's own ID. meta.resources.snapshotId is the public Snapshot ID and returns 404 FetchSnapshotHighlightsNotFound. See Two IDs.
Reads the Appendix of a page the agent already fetched. Where Fetch moved navigation, a footer, or related links out of the Main Markdown, the Markdown carries a marker:
[appendix omitted: 14 links · ~320 tokens] {612}
Option
Definition
Default
snapshotId
meta.snapshotId from an earlier fetch result, or the capture URL from meta.playground.
Required
id
The evidence ID from a marker, such as 612. Returns that block only.
The whole Appendix
Field
Definition
markdown
The requested Appendix content as Markdown.
evidenceId
The id that was asked for, when there was one.
playground
The capture link for the whole Snapshot.
,
The tool reads the public Snapshot routes on the Playground host. It needs no API key and starts no new Fetch.
Note
The counts in a marker say how much is behind it. The tool description tells the agent to read a block only when the task needs it, because the Appendix can be larger than the page.
Snippets and citations
Every snippet from fetch or get_snapshot has these fields:
Field
Definition
source
Where the snippet came from: markdown, appendix, or statejson.
text
The matched passage.
json
The matched value, when source is .
The server builds the links so the agent does not have to. citationBlock lists up to three of them as a **Sources** block, and on fetch the same block is appended to markdown, so a summary of the page carries its sources with it. State JSON snippets are left out of the block, because extracted page state is not a quotable passage.
Links to the website, the docs, and the dashboard.
expand://start
Expand Start Guide
The link to https://expand.ai/start.md and the prompt that runs it. The guide itself is not copied.
The hosted server always serves them. The local server serves them only with --docs:
expandai mcp run --docs
Note
expandai init and expandai mcp install register expandai mcp run without --docs, so do not assume expand://start exists on a local server. The guide itself is at /start.md. See Docs for agents.
Authentication
The local server uses the same credentials as the CLI, stored by expandai login. The hosted server signs the agent in through the browser, or takes an API key as a bearer token, which it verifies against your organization's keys. Details are on Authentication.