Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get Started

OverviewMCP ServerQuickstartWhy ExpandWays to Use Expand

Fetch

OverviewHow Fetch WorksOutput ModelProgressive DisclosureInclude OptionsDocumentsYouTubeBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

MCP Tools & ResourcesCLI, Skill & HooksCLI CommandsAPI ReferenceTypeScript SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown
Browse docs

Get Started

OverviewMCP ServerQuickstartWhy ExpandWays to Use Expand

Fetch

OverviewHow Fetch WorksOutput ModelProgressive DisclosureInclude OptionsDocumentsYouTubeBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

MCP Tools & ResourcesCLI, Skill & HooksCLI CommandsAPI ReferenceTypeScript SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown

MCP Tools & Resources

Tools and optional documentation resources exposed by the Expand MCP server.

The Expand MCP server gives an agent three native Fetch tools — fetch, fetch_search, and fetch_appendix — plus two documentation resources behind a flag.

It runs in two places, with the same tools either way.

Hosted (recommended)

https://api.expand.ai/v1/mcp

Streamable HTTP, nothing installed. Authorization happens in the browser through OAuth, or with an Expand API key sent as Authorization: Bearer xpnd_…. See MCP Server for the per-client setup.

Local over stdio

expandai mcp run

Clients launch this command from their MCP config, not from a terminal. It reuses the credentials from expandai login, so no key is written into the client's config. Use it offline, or where an editor cannot reach an external endpoint.

{
  "mcpServers": {
    "expandai": {
      "type": "stdio",
      "command": "expandai",
      "args": ["mcp", "run"]
    }
  }

Tools

The server registers three tools. All are read-only and non-destructive.

ToolWhat it does
fetchCaptures a URL in a browser and returns Markdown, optional page metadata, State JSON, appendix, and optional Highlights snippets.
fetch_searchRuns Highlights against an existing snapshot by snapshotId, without capturing the page again.
fetch_appendixReturns appendix content — navigation, footers, related-content blocks — from a stored snapshot, either whole or one block by evidence id.

fetch

Fetches and extracts content from any URL. The response is object-mode output: rendered Markdown, front-matter metadata, and the extracted State JSON evidence. When you pass search, the response also carries ranked snippets under data.search.snippets.

ParameterTypeDefaultDescription
urlstring—The URL to fetch content from.
searchobjectomittedHighlights configuration (see below). When set, the response returns ranked snippets.

The search object takes:

FieldTypeDefaultDescription
querystring—Highlights query. When provided, fetch returns snippets for this query.
maxResultsinteger (1–50)

Example call:

{
  "name": "fetch",
  "arguments": {
    "url": "https://news.ycombinator.com",
    "includeMeta": true,
    "search": { "query": "top front-page stories"

The result includes meta (with snapshotId and a playground link), markdown, the State JSON json evidence array, and, because search was set, data.search.snippets. Keep the returned snapshotId if you want to run more Highlights queries later without re-capturing the page.

fetch_search

Searches a previous fetch by snapshotId without starting a new capture. Use it after a fetch call when you need more evidence from the same page. It reuses the stored artifacts instead of paying for another browser capture.

ParameterTypeDefaultDescription
snapshotIdstring—Snapshot ID returned by a previous fetch response.
searchobject—

The result returns the snapshotId, the ranked search snippets, a durationMs timing, and a whole-snapshot playground link.

Snippets and citations

Every Highlights snippet from fetch or fetch_search carries a citationUrl: a public Playground link that opens the exact passage so a human can audit it. Snippets also expose:

FieldDescription
sourceWhere the snippet came from: markdown, appendix, or statejson.
textThe matched passage.
jsonThe extracted value, present when source is .

Return the citationUrl to the user verbatim whenever you ground a claim in fetched content, so the source stays verifiable.

Optional documentation resources

Add --docs to also expose two local documentation resources alongside the tools:

expandai mcp run --docs
ResourceNameContents
expand://aboutAbout expand.aiKey links: website, docs, and dashboard.
expand://startExpand Start GuideA local copy of the agent and editor setup guide, including the expandai login step and per-host install commands.

First-class installers do not enable --docs by default. Do not assume expand://start exists unless the configured MCP command includes --docs.

{
  "mcpServers": {
    "expandai": {
      "type": "stdio",
      "command": "expandai",
      "args": ["mcp", "run", "--docs"]
    }

Authentication

For local MCP clients, run expandai login once in your terminal. The server uses the same local Expand credentials as the CLI, so there is no API key in your config:

expandai login
expandai whoami

Keep EXPAND_API_KEY out of the primary local config. API keys belong in CI, servers, direct API calls, and other non-interactive setups. For environment-variable configuration, see CLI Commands.

How the tools map to the API

The MCP tools are a thin layer over the Fetch HTTP API. fetch calls JSON-mode Fetch; fetch_search calls the Highlights endpoint. For exact request and response schemas, error responses, and generated examples, open the API Reference, specifically Fetch (JSON mode) and Highlights.

fetch_appendix

Reads content that Fetch moved out of the main Markdown. Wherever a region was removed, the Markdown carries a marker:

[appendix omitted: 14 links · ~320 tokens] {612}

Pass that snapshot's snapshotId with id: 612 to read exactly that block, or omit id for the whole appendix. It reads the stored snapshot, so it starts no new capture and costs no fetch.

ParameterTypeDefaultNotes
snapshotIdstring—Handle from a previous fetch: meta.snapshotId.
idnumber—

The result carries markdown, a whole-snapshot playground link, and a ready-to-append citationBlock.

Related pages

  • MCP Server setup
  • CLI Commands
  • Highlights
  • Output Model
PreviousBatched Fetch
NextCLI, Skill & Hooks

On This Page

Hosted (recommended)Local over stdioToolsfetchfetch_searchSnippets and citationsOptional documentation resourcesAuthenticationHow the tools map to the APIfetch_appendixRelated pages
}
includeMetabooleanfalseInclude page meta tags (title, description, Open Graph).
includeAppendixbooleanfalseInclude extracted links and sidebar content.
includeJsonbooleantrueInclude State JSON extracted from network responses and the DOM.
5
Maximum snippets to return.
minScorenumber (0–1)0Minimum snippet relevance score.
,
"
maxResults
"
: 5 }
}
}
Highlights configuration: query, maxResults (1–50, default 5), minScore (0–1, default 0).
includeMarkdownbooleantrueSearch the stored Markdown corpus.
includeAppendixbooleanfalseSearch extracted appendix content.
includeJsonbooleantrueSearch stored State JSON.
statejson
scoreRelevance score from 0 to 1.
citationUrlPublic Playground link auditing this exact snippet.
}
}
Evidence id from an [appendix omitted: …] {N} marker. Omit for the whole appendix.