a2web

Agent-to-Web: adaptive web fetching as an MCP server and CLI for AI agents. Built directly on fastmcp, with shared substrate from the shelf.

Why

Most agent web tools, Claude Code's WebFetch included, silently fail on Reddit, Hacker News, Cloudflare-protected sites, and JS-heavy SPAs. That's exactly where the content worth reading lives. The agent gets an empty page or a block screen, shrugs, and moves on. The finding is lost.

a2web turns one tool call into an autonomous tier cascade. Site handlers go first, then a TLS-impersonating raw fetch, then reader and archive fallbacks, with a stealth browser held back as a last resort. You get the best content it could reach, plus a structured trace of how it got there, so the agent never has to re-decide routing.

The primary tool, query, goes a step past fetching. It runs a small fast model server-side to pull a focused answer out of the page, so your agent's context stays small. The page gets read for you. Only the answer comes back — plus a cheap index of what was left behind, so withholding the body never hides anything.

Status

v0.48. Cascade and extraction are feature-complete. See CHANGELOG.md for what shipped and BACKLOG.md for deferred work.

Install

a2web is not on PyPI (it depends on git-pinned shelf packages). Install it from the repo by tag, or pull the published container image — see Deployment for the container, which is the canonical way to run it as a service.

uv tool install 'a2web @ git+https://github.com/yoselabs/[email protected]'
a2web --help

The base install is lean. Heavy, situational capabilities are opt-in extras so a server deployment stays small:

Extra	Adds	For
[browser]	patchright + zendriver (stealth Chromium rungs)	JS-heavy / hard anti-bot sites without a paid tier. First browser use pulls a Chromium once.
[cookies]	browser-cookie3	mirroring your local browser cookies (local-only; see Cookies).
[claude-code]	claude-agent-sdk	the Claude Code OS-session LLM backend (OAuth piggyback).
[paid]	firecrawl-py	the env-gated Firecrawl paid tier.

uv tool install 'a2web[browser,cookies,claude-code] @ git+https://github.com/yoselabs/[email protected]'

From a clone, make install-global does the same with every extra.

As an MCP server

The canonical deployment is the container over HTTP (see Deployment); point your MCP client at that endpoint:

{
  "mcpServers": {
    "a2web": { "type": "http", "url": "https://<your-gateway>/a2web/mcp" }
  }
}

A local install can also serve over stdio, which is handy for development and for the browser/cookie paths that only work on a real desktop:

{
  "mcpServers": {
    "a2web": { "command": "a2web", "args": ["serve"] }
  }
}

Quickstart

No config needed. fetch_raw works with no keys at all; query needs an LLM backend, because the extraction runs server-side.

# 1. Raw fetch — no keys, no LLM. Proves the cascade works.
a2web web fetch_raw --url=https://news.ycombinator.com/

# 2. Point at any OpenAI-compatible backend (or set ANTHROPIC_API_KEY)
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.deepseek.com
export OPENAI_MODEL=deepseek-v4-flash

# 3. Ask the page a question — the model reads it, you get the answer
a2web web query --url=https://news.ycombinator.com/ --query="top stories, AI"

You get back an answer plus confidence, and — since the body was withheld — also_here / other_pages telling you what else was on the page and where to go next. Add --debug for the timing, cache, and tier-by-tier trace.

Without an LLM backend, query returns a loud llm_unavailable operator hint rather than a silent empty answer.

Tools