> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP tool reference
> Every tool the Zenrows MCP server exposes, with read/write classification, authentication, credits and limits, error codes, and full parameters for scrape, extract, and account_usage.
This page lists the tools the [Zenrows MCP server](/mcp/overview) exposes at `https://mcp.zenrows.com/mcp`, how each one is classified, and the parameters, outputs, and errors of the `scrape`, `extract`, and `account_usage` tools. For setup, see [Remote MCP server](/mcp/overview#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, or a page inside a cloud browser session. Only `batch_cancel` is annotated as destructive.
| Tool | Classification | Acts on |
| - | - | - |
| `scrape` | Read-only | Reads one web page |
| `extract` | Read-only | Reads one web page |
| `account_usage` | Read-only | Reads your plan and credit usage |
| `batch_create` | Write | Creates a Batch job on your account |
| `batch_status` | Read-only | Reads a Batch job |
| `batch_results` | Read-only | Reads a Batch job's results |
| `batch_wait` | Read-only | Reads a Batch job until it finishes |
| `batch_cancel` | Write, destructive | Stops a running Batch job |
| `browser_navigate` | Write | Opens a cloud browser session or navigates it |
| `browser_close` | Write | Closes a cloud browser session |
| `browser_go_back` | Write | Navigates a browser session back |
| `browser_go_forward` | Write | Navigates a browser session forward |
| `browser_reload` | Write | Reloads the page in a browser session |
| `browser_click` | Write | Clicks an element on the page |
| `browser_hover` | Write | Hovers over an element on the page |
| `browser_type` | Write | Types text into an element |
| `browser_fill` | Write | Sets the value of an input |
| `browser_select_option` | Write | Selects an option in a dropdown |
| `browser_check` | Write | Checks a checkbox |
| `browser_uncheck` | Write | Unchecks a checkbox |
| `browser_focus` | Write | Focuses an element |
| `browser_press_key` | Write | Presses a key on the page |
| `browser_scroll` | Write | Scrolls the page |
| `browser_drag` | Write | Drags an element |
| `browser_evaluate` | Write | Runs JavaScript on the page |
| `browser_set_cookies` | Write | Sets cookies in a browser session |
| `browser_clear_cookies` | Write | Clears cookies in a browser session |
| `browser_local_storage` | Write | Reads or writes local storage in a browser session |
| `browser_new_tab` | Write | Opens a tab in a browser session |
| `browser_switch_tab` | Write | Switches tabs in a browser session |
| `browser_batch` | Write | Runs several browser actions in one call |
| `browser_get_accessibility_tree` | Read-only | Reads the page's accessibility tree |
| `browser_get_url` | Read-only | Reads the current URL |
| `browser_get_title` | Read-only | Reads the page title |
| `browser_get_text` | Read-only | Reads text content |
| `browser_get_attribute` | Read-only | Reads an element attribute |
| `browser_get_html` | Read-only | Reads HTML |
| `browser_query_selector_all` | Read-only | Reads all elements matching a selector |
| `browser_screenshot` | Read-only | Captures a screenshot |
| `browser_generate_pdf` | Read-only | Renders the page as a PDF |
| `browser_wait_for_selector` | Read-only | Waits for an element |
| `browser_wait_for_navigation` | Read-only | Waits for a navigation to finish |
| `browser_wait` | Read-only | Waits a fixed time |
| `browser_get_cookies` | Read-only | Reads cookies |
Descriptions of the Batch and browser tools are in [Batch tools](/mcp/overview#batch-tools) and [Browser tools](/mcp/overview#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](/mcp/overview#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](https://app.zenrows.com/settings/api-keys): calls with the old key then fail with `AUTH003`.
## Credits and limits
The Free plan includes 5,000 credits that renew each month; paid plans include larger monthly allowances. Each request costs credits depending on the site and the options used. See [Pricing](/mcp/overview#pricing) for how each tool is billed and [Plans and pricing](/first-steps/pricing) for plan allowances.
When the credits run out, requests fail with `AUTH004` until the allowance renews, or the account tops up or upgrades. A key can also have its own [credit cap](/first-steps/api-key-credit-caps), 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 contains the Zenrows error as JSON, with a `code`, a `title`, and a `detail` that explains the fix.
| Code | Meaning | Retry? |
| - | - | - |
| [`AUTH003`](/api-error-codes#AUTH003) | The API key is not valid, for example after it was rotated | No. Reconnect with a valid key |
| [`AUTH004`](/api-error-codes#AUTH004) | The account's credit allowance is spent | No. Wait for the renewal or upgrade |
| [`AUTH006`](/api-error-codes#AUTH006) | Too many requests running at once | Yes, after current requests finish |
| [`AUTH014`](/api-error-codes#AUTH014) | This API key reached its credit cap | No. Raise the cap or wait for its window |
| [`REQS007`](/api-error-codes#REQS007) | Extract has not prepared this domain yet (`extract` in `auto` mode) | No. `extract` already retries once with `autoparse`; you only see this code when `fallback_autoparse` is `false` |
The full list is in [API error codes](/api-error-codes).
## `scrape`
Fetches one web page and returns its content as Markdown, plain text, HTML, a PDF, a screenshot, or JSON. Built on [Fetch](/fetch/api-reference).
Requests use [Adaptive Stealth Mode](/fetch/features/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
The URL of the page to fetch.
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.
Return the page's main data as JSON.
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`; Adaptive Stealth Mode alone ignores it.
Milliseconds to wait after the page loads, up to 30000. Requires `js_render`; Adaptive Stealth Mode alone ignores it.
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`.
Return a screenshot of the visible part of the page instead of text.
Return a screenshot of the full page.
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
```json Call theme={"dark"}
{ "name": "scrape", "arguments": { "url": "https://example.com" } }
```
```text Result theme={"dark"}
This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.
```
## `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](/extract/introduction).
In its default `auto` mode, `extract` works on domains Extract has prepared. The list is available from [`GET /v1/extract/domains`](/extract/endpoints#which-domains-extract-serves). On other domains it retries once with `autoparse`.
Like `scrape`, every mode uses [Adaptive Stealth Mode](/fetch/features/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
The URL of the page to extract from.
`auto` uses site-tailored extraction (`extract=auto`, open beta) on prepared domains. `autoparse` (deprecated) returns general-purpose JSON on any domain. `css` uses your own selectors from `css_extractor`.
Required when `mode` is `css`. JSON object mapping field names to CSS selectors.
Force rendering in a headless browser on every request. Turns Adaptive Stealth Mode off.
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`; Adaptive Stealth Mode alone ignores it.
Milliseconds to wait after the page loads, up to 30000. Requires `js_render`; Adaptive Stealth Mode alone ignores it.
When `mode` is `auto` and the domain isn't enabled (`AUTH010`) or prepared (`REQS007`) for Extract, retry once with `autoparse`. See [Errors](#errors).
### Output
A JSON object:
| Field | Type | Description |
| - | - | - |
| `ok` | boolean | `true` when the extraction ran |
| `mode` | string | The mode that produced the data |
| `fellBackToAutoparse` | boolean | `true` when `auto` fell back to `autoparse` |
| `empty` | boolean | `true` when no field came back with a value, for example `{ "listings": [] }` |
| `data` | object or array | The extracted fields, or `null` |
### Example
```json Call theme={"dark"}
{ "name": "extract", "arguments": { "url": "https://www.amazon.com/s?k=airpods+pro" } }
```
```json Result (trimmed) theme={"dark"}
{
"ok": true,
"mode": "auto",
"fellBackToAutoparse": false,
"empty": false,
"data": {
"pagination": { "current_page": 1, "total_pages": 20 },
"results": [
{ "position": 1, "asin": "B0FQFB8FMG", "price": 179, "list_price": 249 }
]
}
}
```
## `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
```json Call theme={"dark"}
{ "name": "account_usage", "arguments": {} }
```
```json Result (trimmed) theme={"dark"}
{
"status": "TRIALING",
"period_ends_at": "2026-11-05T14:25:43Z",
"usage_credits": 0,
"credit_limit": 5000,
"usage_percent": 0,
"plan": {
"name": "Free",
"products": { "api": { "concurrency": { "limit": 5, "usage": 0 } } }
},
"api_key": { "caps": [] }
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.