Skip to main content
This page lists the tools the Zenrows MCP server exposes at 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. Only batch_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-resource and can register dynamically at https://mcp.zenrows.com/register. The user signs in at app.zenrows.com, or creates a free account, and approves access.
  • API key as a Bearer token, in the Authorization header. See Authentication.
There is one scope, 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 with AUTH004 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 with isError: 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_recognised or domain_not_enabled. The server reads the API’s reason field when the API sends one. Until the API release that adds that field, the server derives reason from the API error’s title. Either way, the tool result always carries it.
  • next_tool: present only for domain_not_prepared. It holds the prepare_domain call to make, with its arguments.
  • then: present only for domain_not_prepared. It says what to do after that call.
Any 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:
  1. They retry a 429, 502, 503 or 504, and a failure to connect: a refused connection, a name that did not resolve, an unreachable network or host, or a connect timeout.
  2. They return every other status or error at once, because the API may have received the request.
  3. Before each retry they wait the API’s Retry-After in 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.
  4. 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.
  5. When the client’s cancel reaches the server, the wait ends and no new request is sent.
  6. Each retry writes one line to the server’s stderr.
The 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

string
required
The URL of the page to fetch.
boolean
default:"false"
Force rendering in a headless browser on every request. Turns Adaptive Stealth Mode off, which already renders when a page needs it.
boolean
default:"false"
Force residential proxies on every request. Costs more credits and turns Adaptive Stealth Mode off, which already switches to them when a site blocks.
string
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.
string
default:"markdown"
One of markdown, plaintext, pdf, or html. Ignored when autoparse, css_extractor, outputs, or a screenshot option is set.
boolean
Return the page’s main data as JSON.
string
JSON object mapping field names to CSS selectors, for example {"title":"h1","price":".price"}. Returns JSON.
string
Comma-separated data types to return as JSON: emails, headings, links, menus, images, videos, audios, or * for all.
string
CSS selector to wait for before capturing. Requires js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.
integer
Milliseconds to wait after the page loads, up to 30000. Requires js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.
string
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.
boolean
Return a screenshot of the visible part of the page instead of text.
boolean
Return a screenshot of the full page.
string
Return a screenshot of the element matching this CSS selector.

Output

The page content in the requested format: text for markdown, 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

string
required
The URL of the page to extract from.
string
default:"auto"
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.
string
Required when mode is css. JSON object mapping field names to CSS selectors.
boolean
Force rendering in a headless browser on every request. Turns Adaptive Stealth Mode off.
boolean
Force residential proxies on every request. Costs more credits and turns Adaptive Stealth Mode off.
string
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.
boolean
default:"true"
Adaptive Stealth Mode (mode=auto) is on by default. Set false to send a plain request without it.
string
CSS selector to wait for before extracting. Requires js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.
integer
Milliseconds to wait after the page loads, up to 30000. Requires js_render. Without it, including in Adaptive Stealth Mode, it may be ignored.
boolean
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.
boolean
default:"false"
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

string
required
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.
string[]
required
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).
string
Resending the same key with the same body returns the original submission.

Output

The domain’s status record, as GET /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

string
required
The domain passed to prepare_domain.

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 include status, 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)