search, extract, answer, research and a vendor’s live data (live_data_sources,
live_data_source, live_data) — plus browse for a hosted browser agent, the
browser_* tools for driving a browser yourself, and web_run, which picks the
method for a request in words.
It runs as a subprocess of your own client, on your own machine, and reads your
own credentials out of your own environment. There is no hosted service in the
middle and nothing to sign up for: each key is sent only to its own provider,
and to nothing else.
Installing and adding keys are the next two sections; the rest of this page is
reference.
Install, with no credentials at all
The defaultauto chain falls back to backends that need no key, so the first
run needs nothing but a clone and uv:
pip install "webrouter[all]" (or
"webrouter[mcp]" for the server alone) puts web-router-mcp on your PATH,
and uvx --from "webrouter[mcp]" web-router-mcp runs it with no install at all.
An install without the mcp extra has the command too; it prints the line
that installs the extra and exits.
That is a working search and a working extract with no account, no key and
no signup — the keyless backends listed in
Working with no credentials. Then
register it with your client, using the absolute path of your clone:
-
Inside the clone, Claude Code needs nothing: the committed
.mcp.jsonstarts the server, and you approve it once. -
Claude Code, from every project: register it once at user scope.
-
Claude Desktop, Cursor and other clients configured by file: add this
block. Claude Desktop keeps it in
claude_desktop_config.json(Settings > Developer > Edit Config); Cursor in~/.cursor/mcp.json, or a project’s.cursor/mcp.json. Then restart the client.A client started from the desktop often has no shellPATH, so it may not finduv: put the output ofwhich uvincommandinstead.
--project points uv at your clone and keeps the working directory your client
chose. --all-extras turns on every tool, the browser_* ones included, and
lets a fresh clone start before make setup has run; make setup also
installs the Chromium the local browser drives. Without Playwright the server
does not list the browser tools at all.
To see what the server found, ask the model to read the
web-router://capabilities resource: the backends configured per method, where
the keys came from, and unlock, the keys that would add more.
Then add whichever keys you have
The quickest way is one file in your user config directory, which the server reads wherever it starts. On macOS:~/.config/web-router (or
$XDG_CONFIG_HOME/web-router), on Windows %APPDATA%\web-router. Fill in the
keys you hold, then restart the client: a server keeps the environment it
started with, unless the model loads the file with load_env.
Each person brings their own keys: there is no shared key store, and a key
goes from the machine it was set on only to its own provider.
Credentials come from the environment of the process your client launches, and
then from .env files. At startup the server reads every one of four places,
in this order:
An earlier place wins, per variable; a later file only fills what is still
unset, and a credential of two variables (Oxylabs’ username and password,
Bright Data’s token and zone) only as a whole: a file holding half of one sets
none of it, so it never blocks a later file holding both. So a project’s own
.env and a
remembered file can add keys but never replace or complete yours: a repo that
commits a .env with its owner’s key does not take over your traffic. The capabilities resource says which file each variable came
from. The server never creates the user config directory except to record a
remembered path. A WEB_ROUTER_ENV_FILE that names no file is reported rather
than silently skipped. With no file anywhere the server starts keyless.
To use a .env you already keep elsewhere, name it in WEB_ROUTER_ENV_FILE:
env:
"env": {"WEB_ROUTER_ENV_FILE": "/Users/you/work/.env"}. The env block can
carry the keys themselves too — "TAVILY_API_KEY": "tvly-..." — and a variable
the client exports always keeps its value over any file’s.
Whichever file it is, only the provider credentials listed in
.env.example are taken from it. A switch such as
WEB_ROUTER_MCP_ALLOW_FILE_URLS or CHROME_PATH in a file is ignored, because
a server registered at user scope starts in any workspace and that workspace’s
file is not whoever runs the server; ${...} is not expanded, so a file cannot
copy another secret into a provider’s key. The server never writes a
credential anywhere, never sends one to anything but the backend it belongs to,
and never reports one back to the model.
Loading keys mid-conversation: load_env
A model can load a file itself. load_env takes the file’s path — the
model asks you where your .env is, and never asks you to paste a key — and
loads its provider credentials under the same rules, without a restart:
auto at once, and the server sends
notifications/tools/list_changed so the client lists the tools again with the
new provider enums. Browser sessions already open, and research or browse
jobs still being polled, carry on where they started.
remember: true records the path — the path, not a copy of the keys — in
env-path in the user config directory, read after that directory’s own
.env, so it too can only add keys. Delete that file to forget it. A key
rotated in the original file takes effect on the next start. The tool’s
description tells the model to call it only with a path you gave and to set
remember only when you ask.
A remembered path is read in every project the server starts in. When the file
lies outside the server’s working directory, so its keys belong to another
checkout, the capabilities resource’s env starts with a warning naming it
and the record to delete, and the server’s instructions tell the model that
billed backends are live. A setup you believe is keyless can then still bill:
check the warning, or delete env-path.
A key already set is never replaced, so a load can only add backends. That is
also its one risk: a model steered by a page it read could call load_env on a
file someone planted on this machine, adding a key for a backend you hold none
for, and later calls through auto could then run on that account. The result
names every variable a load set, and the capabilities resource lists every load.
What the server found
Theweb-router://capabilities resource carries an env object alongside the
backend lists:
used, missing,
unreadable with a reason, no credentials, or nothing new when an earlier
place had set everything it holds); each variable loaded at startup and the
file it came from; whether WEB_ROUTER_ENV_FILE named a file that is not
there; the variables the client already exported, by name; and each load_env
since. With no provider key at
all it also carries a hint saying how to add one, the server’s instructions
say no keys were found and that the model can ask for a .env path and call
load_env — or carry on keyless — and every other
place the server reports keys says the same thing: names and paths, never
values.
Adding a key changes what the tools offer, because the tools are generated from
what is configured — see below. load_env applies one at once; one changed in
the client’s env block or a file the server already read takes a restart.
The tools
Each tool also carries a
title and MCP’s behaviour hints (readOnlyHint,
destructiveHint, idempotentHint, openWorldHint), so a client can let a
free lookup through and ask before a billed run or a click on a live page.
Here readOnlyHint means safe to run unasked: it changes nothing you own
and bills nothing. So answer and live_data, which bill every call, are
not read-only, and search and extract are read-only only while no paid
backend is configured for them. Once a key is set, auto tries that backend
first and each call bills, so they lose the hint. Listing and describing
live data sources, polling a job and fetch_raw stay read-only.
The descriptions the model reads say what each tool is for, what it costs and
how long it takes: that is what the model chooses on.
Arguments are the library’s own names; each tool’s schema lists them. Anything
the library refuses, this refuses in the library’s own words, and an argument a
tool does not declare — a typo, a guessed option — is refused before anything
runs, with the names it takes.
search offers an option only when a backend reachable from here maps it, and
search_depth only at the levels one serves, as browser_open narrows
stealth. With no key the keyless tier between them (Nimble keyless, You.com
MCP, Exa MCP, Tavily keyless, Keenable) maps every search option. The tool’s description
tells the model that search_depth is how much text comes back per result and
effort how hard the backend looks, and that higher effort costs more and
takes longer, so it leaves effort unset unless needed.
Over MCP the model chooses max_results, not you. Its description steers it
away from a single result, but the choice stays the model’s. A host that wants
the number fixed should wrap search itself.
research never blocks the session
A research run takes minutes and an MCP client talks over one pipe. So
research submits the run, waits 25 seconds, and either answers outright or
hands back a handle with the run still going. Poll research_status with that
handle — calling research again would start, and pay for, a second run.
browse and browse_status work the same way, and each status tool refuses a
handle from the other.
Routing and budgets: web_run, budget_start, budget_status
Experimental, as routing is in the library.
web_run(prompt, max_cost_usd?, time_limit_s?, dry_run=false) is
AsyncWebRouter.run over MCP: the router plans the prompt — the method, its
options and the backend order — and the server runs it. The result is the
method’s own tool output (search’s, extract’s, …) with tool, the
method that ran, a handle for fetch_raw, and the decision record.
dry_run=true returns the plan alone and calls nothing. max_cost_usd and
time_limit_s cap that one call, planning included, within the budget
below; each must be a positive, finite number. When the router picks
research or browse, web_run waits as those tools do, 25 seconds or less
if its own time_limit_s or the budget has less left, and then hands back a
handle for research_status or browse_status. The other tools are
unchanged: search, extract and the rest never ask the router.
The router is set by the operator — whoever starts the server and sets its
environment — once, when the server starts:
-
unset, the built-in rules router (
rules, also the library’s default): a prompt with anhttp(s)URL is read withextract; one asking for a report, a comparison or an in-depth analysis runsresearch, billed per run, orsearchwhen no research backend is configured; anything else is searched.WEB_ROUTER_MCP_ROUTER=rulesnames it; -
WEB_ROUTER_MCP_ROUTER=<module>:<attribute>names a router in a module you installed — any formrouter=takes on the library. It is imported before any.envfile loads, so code that runs at import sees only the server’s own process environment. The built-in decision-API routers,llmandsystemone, need arouter_config: name them withWEB_ROUTER_MCP_ROUTER_CONFIG, below, or build one here: amy_router.pyholdingandWEB_ROUTER_MCP_ROUTER=my_router:ROUTER. The preset’s key (OPENAI_API_KEY,TYPESAFE_API_KEY, …) is read from the server’s environment when it starts. Eachweb_runthen sends that vendor the prompt, its URLs whole, the budget and the candidate ids with their estimated cost and p90 latency, never a provider key; -
WEB_ROUTER_MCP_ROUTER=remoteasks your router service over HTTP, the library’s built-inremoterouter:WEB_ROUTER_REMOTE_ROUTER_URLis its URL (https, orhttptolocalhostor a loopback address; no credentials or query) andWEB_ROUTER_REMOTE_ROUTER_API_KEYits optional bearer key, both read once from the same process environment at startup; -
WEB_ROUTER_MCP_ROUTER=<name>names any other built-in router, such asfallback, with itsrouter_configas a JSON object inWEB_ROUTER_MCP_ROUTER_CONFIG, the same keys the library takes, flat for one router:WEB_ROUTER_MCP_ROUTER=llm WEB_ROUTER_MCP_ROUTER_CONFIG='{"preset": "openai", "model": "gpt-4.1-mini"}'. Onlyweb_runasks the router here, soroute_toolsin the config changes nothing. A config entryapi_key_envnames the variable holding a key: its value is read once at startup and put in its place asapi_key, so the router never reads the environment again. When the variable is unset,remotestarts with no key (""), whilellmandsystemonestop the server from starting. For example, a router service with a local classifier service behind it:Set,WEB_ROUTER_MCP_ROUTER_CONFIGis the whole config:remotethen takes its URL from it, not fromWEB_ROUTER_REMOTE_ROUTER_URL. Aremoterouter or member whose config sets noapi_key(norapi_key_env) still sendsWEB_ROUTER_REMOTE_ROUTER_API_KEY, read when it is built at startup. A router’s key comes from the server’s own process environment only. Anllmorsystemonepreset given no key reads its vendor’s variable (OPENAI_API_KEY,DEEPSEEK_API_KEY,TYPESAFE_API_KEY…), which is often a provider credential too. The server captures it, and everyapi_key_env, asapi_keyat startup, before it reads any.envfile, so neither a project’s.envnorload_envcan supply or replace a router’s key: export it where the server starts. A preset’s variable that is unset there stops the server, and a vendor’s variable named for a router that posts to any other host is refused. The capabilities resource names a preset’s host too, as the record does:llm(api.openai.com),systemone(api.typesafe.ai). A value that is not a JSON object, or one set beside no built-in router, stops the server; -
WEB_ROUTER_MCP_ROUTER=offattaches none:web_runthen plans the static order, which issearch.
WEB_ROUTER_MCP_ROUTER imports and runs your code when the server starts, so
set it in the server’s own process environment, never in a project’s config
or a .env file. Set empty, it stops the server from starting.
Plans hold to url_policy="public_only": a URL in a prompt that names a
loopback, private or cloud-metadata host is not sent to a backend as a URL.
It is a check of the host as written: it resolves no DNS and follows no
redirect. The same check holds for the URLs an agent passes the direct tools:
extract’s urls, browse’s start_url and any URL among live_data’s
inputs that is not a public http(s) one — file:, loopback, private,
metadata — refuses the call before anything is sent, naming the URL’s scheme
and host and why. So a page that steers the model cannot have your keyed
account hand a vendor an intranet or metadata URL. The browser
tools have their own guard (Where the browser may go),
which checks DNS answers and redirects but refuses only cloud metadata hosts
and the browser’s debugging port: other loopback and private hosts are
admitted there. A refused URL stays in the prompt text, though, and the prompt
itself goes to the backend that serves it, as its search query or browse task, as it
would through search. The built-in router runs in the server’s process and
sends nothing out; an operator’s router runs there too, but it is your code,
and may send the prompt on, to a model’s server for instance. The remote
router sends each web_run prompt, the URLs in it whole, the budget and the
candidate ids (tool:provider, which name the backends configured here) to
your service, and never a key value; a service that fails or runs past its
time leaves web_run on the static order. A fallback router sends the
same to every service it asks, in order, one that times out included.
The budget. Every billed tool — search, extract, answer, research,
browse, live_data, browser_open and web_run — spends from one budget
per connection, a shared budget as wr.budget(...) is in the library. Each
attempt reserves its estimated list price before it starts, and a call that
does not fit is refused with BudgetExceededError before anything bills. A
live data run is charged its list price; a cloud browser per minute of its
lifetime (timeout), rounded up to whole minutes, on the dearest backend that
can serve the options asked for. A browser option that can bill an extra
charge (a proxy country, stealth, CAPTCHA solving, a profile) makes a paid
backend’s price unknown. Under a cost cap a backend whose price is
unknown never runs, and the refusal names the unknown price. So extract with
provider="max", which races every member at once and has no price before the
race, is refused under a cost cap; name a backend or use auto. The calls the
server charges itself run on the budget’s clock, and research and browse
wait no longer than it has left.
-
The operator’s ceiling:
WEB_ROUTER_MCP_MAX_COST_USDandWEB_ROUTER_MCP_TIME_LIMIT_S. It counts what the backends charge; a router that bills for itself, such asllmorsystemone, is billed by its vendor and is not counted. With nobudget_start, the whole connection is one task under it, its clock running from the connection’s start. The agent cannot reset or raise it. -
budget_start(max_cost_usd, time_limit_s)opens a new task inside the ceiling, with both limits stated each time — positive, finite numbers, or the call is refused — and a clock from now. Each reservation must fit the task and the ceiling, so the limits are cut to what the ceiling has left. A call still running when a new task starts stays charged to the connection. -
budget_status()returns the task in force, the connection’s totals and the ceiling:budgetisnullwith no ceiling and nobudget_start. Itsmax_cost_usdandtime_limit_sare those in force, cut to the ceiling, andremaining_usdcounts against the ceiling too;connectionis what every task on the connection has spent and reserved.ceilingis always there, each limitnullwhen the operator set none.
budget_start, nothing is held, and every tool runs as
it would with no budget.
These variables are read from the server’s own process environment, once,
at startup. No .env file and no load_env call can set or change them, and a
value the server cannot read — an empty one included — stops it from
starting rather than leaving the connection without the ceiling you meant. The capabilities resource reports
all of it under routing: the router (rules, operator for yours — never
its <module>:<attribute> — remote(<scheme>://<host>) for a service, never its path, query or key,
fallback(<member>, ...) for a fallback, or
off), where it runs (router_runs: in_process for the built-in router or
none, operator with a router_note for yours, remote with a router_note naming each host prompts go to —
a service, or a built-in llm or systemone router’s vendor host —
built_in for a built-in router whose config names no URL),
a prompt_note saying the
prompt goes to the backend, and to each router service’s host, the url_policy with a url_policy_note saying
where it holds, the ceiling, and the budget in
force (null with none).
A browse result never carries its session
A browse task’s payload can include the session the agent ran in — a live view that controls the browser without a key, a CDP (Chrome DevTools Protocol) URL with the account key in its query string. So every browse output — the shaped result,browse_status,
fetch_raw on a browse handle — and every tool’s error message, whatever the
tool (a vendor’s HTTP error body can ride on any method’s failure) — replaces
these with [redacted]:
- Everything beneath a credential-named field, however nested:
token,apiKey,signingKey,jwt,secret,password/passwd,privateKey,accessKey,authorization,auth,cookie/set-cookie,credentials, and the plural or*Token/*ApiKeyforms of them. - Any URL beneath a session-named field: a live view, debugger, devtools,
inspector, CDP, websocket, connect or connection endpoint —
liveViewUrl,debuggerFullscreenUrl,wsEndpoint,connectUrl,CDPURLand the like, matched in any case, with or without separators. - Any URL that is a session on its face, wherever it appears, free text
included: a
ws:///wss://scheme; a username or password in it;devtools,cdp,liveordebugin its host or path, as inhttp://127.0.0.1:9222/devtools/browser/…; or atoken,apiKey,x-api-key,signingKey,jwt,key,auth,access_token,signatureorsigquery or fragment parameter.
note says how many values were replaced. Every other handle’s
payload is returned verbatim, except browser_read’s, below.
Driving a browser
browse hands a whole task to someone else’s agent. The browser_* tools are
for when the model is the agent: it opens a session, looks at the page, and
decides every click itself.
The server holds the session; the model holds an id
A model cannot hold a browser handle or run awith block, so the server keeps
every session it opened in a table and gives the model a random id it minted,
browser-…. That id is all the model ever sees. The CDP URL — a credential:
whoever holds it drives the browser, and several backends put the account key
in it — the backend’s own session id and any live-view URL stay in the server.
Every browser tool’s output and error message goes through the same redaction
as a browse result, and on top of it every one of those values is replaced
literally wherever it appears, so a page that quotes its own debugging endpoint
still does not hand it over. browser_read stores the page already scrubbed,
so fetch_raw on its handle can only return what is safe.
Each session keeps one handle and one CDP connection for its whole life —
several backends end a session when its CDP client disconnects — and runs one
action at a time.
What browser_open takes, and what it does not
provider (the browser backends configured here, local always among them),
headless, timeout (the session’s lifetime: 600 seconds when unset, and at
most 600 however it is set), idle_timeout, viewport, proxy_country,
stealth ("off", "low" or "high") and solve_captchas — but only the
ones a backend configured here maps, as for every other tool, and stealth
only at the levels one of them serves. auto is read as the chain it would
try, since it declares everything and routes each request to a member: with no
key at all that is local, so the schema offers headless, timeout and
viewport and nothing else. A backend refuses an option it does not map, or a
value of one it cannot serve, rather than ignoring it — an option sent anyway
reaches the library and its error, never a silent drop.
With no provider, auto picks one, and stealth at any level ("off"
included), proxy_country or solve_captchas pass over local, which offers
none of them. Only a cloud
vendor can serve them, and every cloud vendor bills for the session. The
browser_open description says so to the model; leave those three unset, or
pass provider="local", to stay free.
It deliberately does not take provider_options, which reach the backend
untranslated — for local they are Chrome command-line switches — or profile
/ persist_profile, a saved, logged-in identity you own. Those are set in code,
never from a conversation, and passing one is refused by name.
The tools need Playwright: install webrouter[mcp,browser]. Where it is
missing the server leaves every browser_* tool out of its tool list, and a
client that calls browser_open anyway is refused before a session is opened —
and billed for — that nothing could drive.
Where the browser may go
A model driving a browser takes its instructions from the pages it reads, so a page can tell it where to go next. Onlocal that browser runs on your machine,
beside its own debugging endpoint, your files and, on a cloud VM, the metadata
service that hands out the machine’s credentials. So the browser tools open
only http: and https: pages and about:blank, and refuse:
What is deliberately not refused: loopback and private-network (RFC 1918)
addresses, beyond the session’s own CDP endpoint and the metadata ranges above.
A dev server on
localhost:8000 or an intranet page is a legitimate thing to
point a browser on this machine at — but it also means a page can steer the
model toward one, and what it serves enters the transcript. Run the server
(and pick local sessions) on a machine whose network holds nothing a
page-steered model should not read.
The policy is enforced at these points:
browser_gotorefuses a URL before the page is touched. Decimal, hex, octal and short IPv4 spellings (2130706433,0x7f000001,127.1) are read as the address they spell, and a NAT64 or IPv4-compatible IPv6 address as the IPv4 it carries.- A Playwright route on the browser context sees each request’s first hop and
aborts one to a refused address — a link, a form, a script’s
fetch, a WebSocket. It does not see redirect hops: Playwright routes only the first request of a chain. For a host that is a name rather than an address, the route also resolves it, on a worker thread, and aborts the request if any address it resolves to is link-local or a metadata address, or is the session’s CDP host on the CDP port — sohttp://my-alias.example:9222/jsonpointing at127.0.0.1is refused likehttp://127.0.0.1:9222/json. - The server records, while an action runs, every navigation request — redirect hops included — and every committed frame navigation, in the main frame or any subframe, that reaches a refused address. That catches a frame sent somewhere refused and removed again before the action ends.
- After the action it checks the URL of the page and of each frame still attached, and resolves every DNS name the recorded navigations touched — so a redirect hop or a frame sent to an alias of a refused address, which the route never resolved, is still caught before the action’s result is returned.
about:blank and the
action returns a refusal instead of its result, so nothing the action read is
handed to the model.
What this does not guarantee: a subresource that is not a navigation — an
image, a script’s fetch — redirected to a refused address is not aborted,
because the route never sees the hop; what the browser’s own rules allow the
page to do with the response is up to the browser. Only the browser_* tools’
results are held back: a page’s scripts ran, and anything they sent elsewhere
was sent. The checks watch the session’s own page and context; a popup’s frames
are covered by the request record and the route, not by the frame checks.
Blocking the CDP port inside the browser as well, through CDP
Network.setBlockedURLs, was tried and did not stop a redirect hop over a
connect_over_cdp connection, so it is not used.
The DNS check narrows DNS rebinding; it does not close it. The route’s lookup
and the browser’s are two separate lookups: once the route lets a request
through, Chrome resolves the name again with its own resolver and cache, and
connects to whatever that answer is. A name served with a short TTL can answer
the route with a public address and the browser, a moment later, with
169.254.169.254 or 127.0.0.1. Nothing pins the browser’s connection to the
address that was checked, so a server that times its answers can still reach
a refused address. What the check does rule out is the plain alias — a name
that always resolves to a refused address, whether it was a first hop the route
saw or a redirect hop resolved when the action settled — and a rebinding that
has already flipped by the time it is looked up. Other limits of the same
check: a name that does not resolve here is let through (the browser’s lookup
fails the same way, unless its resolver — DNS over HTTPS, say — differs from
the system one); and a CDP host that is itself a name, as on a cloud vendor, is compared by name
and loopback alone, not by the addresses it resolves to.
An operator who needs local files — a test fixture, say — sets
WEB_ROUTER_MCP_ALLOW_FILE_URLS=1 where the server runs. It is an environment
variable and never a tool argument, so a conversation cannot turn it on, and it
opens file: alone.
Snapshots, refs and errors
browser_snapshot returns the tree as its own text block, capped at 40,000
characters (about 10,000 tokens) unless the call passes max_chars. That is
far more than the 8,000 a search result gets, because a ref past the cut cannot
be clicked; it holds the whole tree of a typical article, results page or form.
A cut tree says so in truncated and note.
A ref is good until the next snapshot or navigation. browser_click and
browser_type check before touching the page that exactly one of ref and
selector was given and that the ref looks like one (e14, not [ref=e14]).
A failed action comes back as an error saying what to do next: a stale ref says
to take a new snapshot, a missing selector to check it or use a ref, a timeout
to retry or pass a larger timeout. A page or connection that is gone releases
the session and says to open a new one.
Nothing is left running
The input schemas carry the same maximums, so a client that validates arguments
refuses a larger value before the server sees it.
A model that forgets
browser_close costs five minutes of a session, not an
afternoon. What the server cannot do is release a session after it stops
running: SIGKILL, a crash of the interpreter, or a client that kills the
server sooner than the 30 seconds the release may take leaves sessions behind.
A cloud session bills until the vendor ends it at the end of its lifetime,
which is why every session is opened with one; a session a vendor started while
browser_open timed out is covered the same way. A local Chrome is
orphaned: its lifetime is a timer inside the server process, so it dies with
the process, and the browser keeps running until you quit it (pgrep -fl remote-debugging-port finds it).
The tools describe your install, not the package
Every install holds a different set of keys, so theprovider argument’s enum
is generated when the client lists the tools, from the backends this machine
holds keys for. Hold only a Tavily key and that is what the enum says; the
model is never shown thirteen backends it cannot reach, and cannot pick one
that is certain to throw. With no key at all, search and extract offer auto
and the keyless backends listed in
Working with no credentials (and
extract also max, which races them); research and browse offer only auto,
which has nothing to run on; and the live data tools and answer offer nothing,
since every backend bills. Once a key is set, answer with no provider tries
the configured answer backends in ranked order. A tool with nothing to run on
says so in its own description, in as many words, rather than pretending to
work.
The resource web-router://capabilities carries the same lists as JSON, plus browse and browser
— the three live data tools under one live_data key —
so a client can learn what this install can do without a round trip through the
model — and the env object above, saying where those
keys came from.
Result shaping: the one place this differs from the library
The library’s rule is that nothing is thrown away — full page bodies, and the backend’s untouched response underraw. Inside a context window that rule is
actively harmful: one deep search can be larger than the window it is read in.
So a shaped result:
- keeps the fields a reader acts on, and drops
descriptionwherecontentalready holds the same text; - caps the whole response at 8000 characters (
WEB_ROUTER_MCP_MAX_CHARSoverrides it); - cuts long text at a word boundary and marks the cut
... [truncated]; - drops whole results from the end of a list only when trimming text is not enough, and never drops the last one;
- never inlines
raw; - says in the result itself what it cut: the
... [truncated]marker ends a cut field, andtruncatedwith anotenaming the handle is set when the main text (an answer, a page’s content) was cut or results were dropped. A cut search snippet or citation carries only the marker; - keeps what the call cost and how long it took, as the library’s response
carries them:
elapsed_s(seconds, to two decimals),cost_usdandcost_source(reportedby the backend orestimatedfrom list prices) on a search, extract, answer, research or browse result — a finishedresearch_statusorbrowse_statusincluded — and left out when unknown. No cut ever touches them; - comes back as JSON text and, for a client that reads it, the same object as
structuredContent.
handle. fetch_raw takes it and returns the backend’s
untouched payload, uncapped — nothing is lost, it is just not spent on the
context window unless you ask for it. The session keeps the 64 most recent
handles and evicts the oldest, so a long conversation stays bounded.
Everything else — parameter names, provider selection, error messages — is a
thin projection of the library. A failure comes back as a tool error carrying
the library’s own message, which names the environment variable to set; where
the library would also offer provider_config, which is code, the server says
how to add the key through MCP instead:
Serving fewer tools: WEB_ROUTER_MCP_TOOLS
The model reads every listed tool on every turn: all 27, with every key set,
are about 26 KB (some 6.4k tokens). Name the ones you want, comma-separated, and
the rest are neither listed nor callable:
* matches a prefix. Unset or blank serves every tool; a name that
matches nothing is ignored with a warning in the server’s log. Keep fetch_raw
if results may be cut, and load_env if keys may be added mid-conversation.
Read once at startup, from the real environment only. research, browse and
browser_open each bring their partner (research_status, browse_status,
browser_close), so a long run can still be polled and a browser closed.
Environment variables the server itself reads
Everything else it reads is a provider or vendor credential, and belongs to the provider or vendor.
load_env takes every variable a vendor’s catalog file lists, settings such as DD_SITE included.