Contextfetch MCP Server

@contextfetch/mcp

MCP server for ContextFetch: neural web search and clean, LLM-ready Markdown for AI agents from $0.75 per 1,000 searches. Works with zero signup: no key needed for the free tier.

Install

Claude Code (one line, keyless):

claude mcp add contextfetch -- npx -y @contextfetch/mcp

With a paid key:

claude mcp add contextfetch -e CONTEXTFETCH_API_KEY=your_key -- npx -y @contextfetch/mcp

Cursor: add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "contextfetch": {
      "command": "npx",
      "args": ["-y", "@contextfetch/mcp"],
      "env": { "CONTEXTFETCH_API_KEY": "your_key" }
    }
  }
}

Windsurf: add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "contextfetch": {
      "command": "npx",
      "args": ["-y", "@contextfetch/mcp"],
      "env": { "CONTEXTFETCH_API_KEY": "your_key" }
    }
  }
}

To use the free tier, drop the env block (or leave CONTEXTFETCH_API_KEY empty). The same JSON works in Claude Desktop's claude_desktop_config.json and in any other MCP client that launches stdio servers.

Requires Node.js 18 or newer.

Tools

All tools return Markdown text. Without a key, contextfetch_balance and contextfetch_auto_reload return a short message saying they need one, with the buy link. On the free tier, results start with a one-line notice showing how many free searches are left today. When the API reports them, a closing line shows latency (total and per stage: recall, fetch, rerank), whether the answer came from cache, and token savings (pruned tokens vs raw page tokens).

contextfetch_research sub-queries

Pass your own sub_queries (different angles on the question); the tool description tells the calling model to do so. If you omit them, the API derives them from query with fixed rules:

1. the query itself;
2. the query + documentation;
3. the query + benchmark when it mentions speed, performance, latency, memory or a comparison (vs, compare), otherwise the query + example.

A suffix the query already contains is skipped (so react useActionState example runs 2 searches, not 3). The whole research runs server-side in one /v1/research call that costs 1 credit per sub-query; a sub-query that fails is refunded and named in the header. If all fail, the tool returns the error.

Environment variables

Free tier and pricing

One-time payments; credits never expire. Optional auto-reload re-buys a pack when your balance drops below a threshold, up to a monthly cap.

When credits or the free tier run out (HTTP 402), the tool returns the packs with prices and a one-click buy link each (recommended pack first), plus a line to pass on to your user. Buy links go straight to Stripe Checkout (card, Apple Pay, Google Pay): https://api.contextfetch.dev/buy/instant, /buy/builder, /buy/scale. Then set CONTEXTFETCH_API_KEY as shown above.

Retries and connections

Connection failures before the request is sent (refused, DNS, connect timeout), HTTP 429 and HTTP 5xx are retried with exponential backoff and jitter (about 0.25-0.5 s, then 0.5-1 s), at most 3 attempts per API call and 30 seconds in total, retries included. A 429 or 5xx with a Retry-After header waits exactly that long, unless that would pass the 30 second budget. 400, 401, 402, 422 and other 4xx responses are never retried. A connection that drops after the request was sent is not retried either, since the search may already have been billed. Connections are pooled and kept alive by Node's built-in fetch (undici), so there is no extra HTTP dependency.

Errors

Errors never crash the server; they come back as tool results with isError: true and a plain explanation: invalid key (401), out of credits or free limit reached (402, lists the packs with their buy links), no saved card for auto-reload (409, with the buy link), URL not allowed (400, only public http(s) URLs), a page contextfetch_extract_url could not fetch (with the reason, such as HTTP 404), rate limited (429), server errors (5xx), network failures, and a 30 second limit per call (retries included).

Develop

npm install
npm run build          # compiles src/ to dist/ and marks dist/index.js executable
npm test               # builds, then drives dist/index.js over stdio against a local mock API (no network)
CONTEXTFETCH_API_BASE=http://localhost:8000 node dist/index.js

Publish

Publishing @contextfetch/mcp needs the npm organization contextfetch (create it at npmjs.com and add the publishing account as a member). Then npm publish from this folder; publishConfig.access is already public and prepublishOnly builds first.

License

MIT