Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

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

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython 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 two native Fetch tools — fetch and fetch_search — and, with a flag, two documentation resources. It runs locally over stdio:

expandai mcp run

Most clients should launch this command from their MCP config, not from a terminal. Authenticate once with expandai login; the server reuses your local CLI credentials.

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

Different clients name the surrounding fields differently. See Other MCP Clients for JSON and TOML variants, or use a first-class installer for Claude Code, Cursor, Codex, or OpenCode.

Tools

The server registers two tools. Both 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

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 additional 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 surface 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.

Related pages

  • Other MCP Clients
  • CLI Commands
  • Highlights
  • Output Model
PreviousCLI Commands
NextTypeScript SDK

On This Page

Toolsfetchfetch_searchSnippets and citationsOptional documentation resourcesAuthenticationHow the tools map to the APIRelated 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.
}
}