https://mcp.zenrows.com/mcp, how each one is classified, and the parameters, outputs, and errors of the scrape, extract, prepare_domain, prepared_domain_status, and account_usage tools. For setup, see Remote MCP server.
Tool classification
The classification comes from each tool’s MCP annotations. Read-only tools retrieve information and change nothing. Write tools change state: a job on your account, a file of crawl results, or a page inside a cloud browser session. Onlybatch_cancel, batch_delete, crawl_stop, browser_clear_cookies, browser_clear_local_storage, browser_set_cookies, browser_set_local_storage, browser_evaluate and browser_batch are annotated as destructive, because they can delete or overwrite data on your account or in a browser session.
Descriptions of the Crawl, Batch, and browser tools are in Crawl tools, Batch tools, and Browser tools.
Authentication and permissions
The server accepts either of these on every request:- OAuth 2.1 with PKCE (S256). Clients discover the authorization server through
https://mcp.zenrows.com/.well-known/oauth-protected-resourceand can register dynamically athttps://mcp.zenrows.com/register. The user signs in atapp.zenrows.com, or creates a free account, and approves access. - API key as a Bearer token, in the
Authorizationheader. See Authentication.
api. The access token is the account’s API key, so every tool runs with the same permissions as that key. To revoke access, rotate the API key in the dashboard: calls with the old key then fail with AUTH003.
Credits and limits
The Free plan includes 5,000 credits that renew every billing period (an unclaimed agent account gets only its first period; see Agent signup and unclaimed accounts); paid plans include larger allowances. Each request costs credits depending on the site and the options used. See Pricing for how each tool is billed and Plans and pricing for plan allowances. When the credits run out, requests fail withAUTH004 until the allowance renews, or the account tops up or upgrades. An unclaimed agent account is the exception: it is not renewed, and once its first period ends, requests fail with AUTH005 until a person claims it. A key can also have its own credit cap, which returns AUTH014.
Each plan also limits how many requests run at once. Requests over that limit fail with AUTH006. account_usage does not count toward the concurrency limit.
Errors
A failed tool call returns a tool result withisError: true. The text of the result is JSON with the error code, a message that names the fix, and detail, which carries the Zenrows API error it came from.
For REQS007 from extract, the MCP server adds three fields of its own:
reason:domain_not_prepared,page_not_recognisedordomain_not_enabled. The server reads the API’sreasonfield when the API sends one. Until the API release that adds that field, the server derivesreasonfrom the API error’s title. Either way, the tool result always carries it.next_tool: present only fordomain_not_prepared. It holds theprepare_domaincall to make, with its arguments.then: present only fordomain_not_prepared. It says what to do after that call.
extract error also carries a note when the call sent the deprecated fallback_autoparse: true. The note says the option was ignored: extract never retries with autoparse.
The full list is in API error codes.
Retries in scrape and extract
scrape and extract send each call once by default. On the local server (MCP server 2.19.0 or later), set the ZENROWS_FETCH_RETRIES environment variable to make them retry, up to that many times, a call the API did not serve. The server reads it once, at startup; see Local MCP server. The hosted server retries only if its operator sets it. With retries turned on:
- They retry a
429,502,503or504, and a failure to connect: a refused connection, a name that did not resolve, an unreachable network or host, or a connect timeout. - They return every other status or error at once, because the API may have received the request.
- Before each retry they wait the API’s
Retry-Afterin whole seconds, from 250 ms to 30 s. Otherwise they wait a random time from 250 ms up to 1 s before the first retry, 2 s before the second, and so on, capped at 30 s. - A retry starts only if its wait ends within 50 s of the first request, because many MCP clients cancel a tool call at about 60 s. A running request is not cut short, so a retry that starts near 50 s can still run past the client’s timeout.
- When the client’s cancel reaches the server, the wait ends and no new request is sent.
- Each retry writes one line to the server’s stderr.
batch_* and crawl_* tools keep their own retry rules. prepare_domain and prepared_domain_status never retry: a 429 from them means the monthly allowance is used up, and a 503 means preparation is unavailable right now.
scrape
Fetches one web page and returns its content as Markdown, plain text, HTML, a PDF, a screenshot, or JSON. Built on Fetch.
Requests use Adaptive Stealth Mode (mode=auto) by default: Zenrows enables JavaScript rendering and premium proxies only when a page needs them, and you pay only for the configuration that succeeds. Setting js_render or premium_proxy forces that configuration and turns Adaptive Stealth Mode off.
Classification: read-only. Makes no changes to the account or to the site it reads.
Parameters
Force rendering in a headless browser on every request. Turns Adaptive Stealth Mode off, which already renders when a page needs it.
Force residential proxies on every request. Costs more credits and turns Adaptive Stealth Mode off, which already switches to them when a site blocks.
Two-letter country code (ISO 3166-1 alpha-2), for example
US. Works with Adaptive Stealth Mode. Without it (when js_render is set), it requires premium_proxy.One of
markdown, plaintext, pdf, or html. Ignored when autoparse, css_extractor, outputs, or a screenshot option is set.JSON object mapping field names to CSS selectors, for example
{"title":"h1","price":".price"}. Returns JSON.Comma-separated data types to return as JSON:
emails, headings, links, menus, images, videos, audios, or * for all.CSS selector to wait for before capturing. Requires
js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.Milliseconds to wait after the page loads, up to 30000. Requires
js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.JSON array of browser actions to run before capturing, for example
[{"click":"#load-more"},{"wait":1000}]. Works with Adaptive Stealth Mode, which then renders the page in a browser, or with js_render.Output
The page content in the requested format: text formarkdown, plaintext, and html; JSON for autoparse, css_extractor, and outputs; an image for screenshots.
Example
Call
Result
extract
Returns a page as structured JSON fields instead of a full page body, for example a product’s name and price. Built on Extract.
In its default auto mode, extract works on any prepared domain. The list of prepared domains is available from GET /v1/extract/domains. On a domain not prepared yet it returns REQS007 with reason domain_not_prepared and the prepare_domain arguments in next_tool. It never falls back to autoparse.
Like scrape, every mode uses Adaptive Stealth Mode (mode=auto) by default. Setting js_render or premium_proxy forces that configuration and turns it off.
Classification: read-only. Makes no changes to the account or to the site it reads.
Parameters
auto uses site-tailored extraction (extract=auto) on prepared domains. autoparse (deprecated) returns general-purpose JSON on any domain. css uses your own selectors from css_extractor.Force residential proxies on every request. Costs more credits and turns Adaptive Stealth Mode off.
Two-letter country code. Works with Adaptive Stealth Mode. Without it (when
js_render is set, or mode_auto is false), it requires premium_proxy.Adaptive Stealth Mode (
mode=auto) is on by default. Set false to send a plain request without it.CSS selector to wait for before extracting. Requires
js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.Milliseconds to wait after the page loads, up to 30000. Requires
js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.Deprecated. Has no effect:
extract never falls back to autoparse. It is still accepted so older prompts keep working; when it is true, the result carries a note saying it was ignored. On REQS007 with reason domain_not_prepared, call prepare_domain instead.auto mode only. Also return the page HTML, which is most of the response size.Output
A JSON object:Example
Call
Result (trimmed)
prepare_domain
Prepares a domain so extract in auto mode works on it. Use it when extract returns REQS007 with reason domain_not_prepared. Built on POST /v1/extract/prepared-domains.
It returns at once and never waits for the preparation, which takes a few minutes and costs no credits. Each new domain uses one slot of your monthly allowance. A domain already being prepared returns its current status instead of submitting again; a domain already prepared returns status: "ready" at once with already_prepared: true and uses no slot.
Do not call it for reason page_not_recognised: that domain is already prepared, and preparing it again does not change the answer.
Classification: write. Submits a preparation on your account.
Parameters
The host to prepare, such as
shop.example.com. A URL is accepted. A leading www. is dropped; any other subdomain is prepared on its own.1 to 5 full URLs of real pages on that host that you want to extract. One works; we recommend 3 or more of the same page type (e.g. 3 product pages), because Extract compares pages of one type to check the fields it found and fill in fields one page is missing. Several page types can share the 5 (e.g. 3 product pages + 2 search-result pages).
Output
The domain’s status record, asGET /v1/extract/prepared-domains/{domain} returns it, plus next: the step to take now. already_prepared or already_in_progress is true when nothing new was submitted.
Errors name the next step: invalid_argument (fix the domain or the URLs), out_of_allowance (no slots left this month; use mode: "css"), and overloaded or disabled (retry in a few minutes; don’t retry in a loop).
Example
Call
Result
prepared_domain_status
Reads how far a domain submitted with prepare_domain has got, and your monthly allowance. Free.
Classification: read-only. Makes no changes to the account.
Parameters
Output
The domain’s status record (status is preparing, ready or failed; state is the current step; failure explains a failed one), allowance (used, limit, remaining, month), and next: the step to take now. Poll about every 30 seconds, and call extract again once status is ready. A domain this account never submitted returns not_found.
account_usage
Returns the current plan, its credit allowance, how much is spent, and when the period renews. Free, and does not count toward the concurrency limit.
Classification: read-only. Makes no changes to the account.
Parameters
None.Output
The account’s subscription details as JSON, passed through from the Zenrows API. Fields includestatus, period_starts_at, period_ends_at, usage_credits, credit_limit, usage_percent, plan (name, products, concurrency limit), and api_key.caps.
Example
Call
Result (trimmed)