Search the live web, look up companies and read any page through the Oxylabs Web API.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Oxylabs Web API key, from a Web API instance in the Oxylabs dashboard.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Collect requests the API is running in the background. Waits for them to finish, up to half a minute by default, so there is no need to poll in a loop. Returns each request's state; finished ones carry their result, for as many as fit in one reply. The rest come as summaries marked `summarized`, holding as much of each page as there was room for: read on with `read_result`. A parser note comes once, in `parser_notes`, and each result names its own. Only the first few screenshots come back as images. If some are still pending, call again with only their request ids.
The `request_id`s of queued requests, from `scrape` or `run_scraper` replies or an earlier call to this tool. A single id is fine.
Pick your client. Values in capitals, like YOUR_TOKEN, are yours to fill in.
Run in a terminal
claude mcp add --transport http web-api-mcp https://mcp.oxylabs.io/web-api-mcp \ --header 'Authorization: YOUR_CREDENTIALS'
Headers
Authorization (required): Oxylabs Web API key, from a Web API instance in the Oxylabs dashboard.Collect requests the API is running in the background. Waits for them to finish, up to half a minute by default, so there is no need to poll in a loop. Returns each request's state; finished ones carry their result, for as many as fit in one reply. The rest come as summaries marked `summarized`, holding as much of each page as there was room for: read on with `read_result`. A parser note comes once, in `parser_notes`, and each result names its own. Only the first few screenshots come back as images. If some are still pending, call again with only their request ids.
| Argument | Type | Description |
|---|---|---|
| request_ids* | array | The `request_id`s of queued requests, from `scrape` or `run_scraper` replies or an earlier call to this tool. A single id is fine. |
{
"type": "object",
"required": [
"request_ids"
],
"properties": {
"request_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 50,
"minItems": 1,
"description": "The `request_id`s of queued requests, from `scrape` or `run_scraper` replies or an earlier call to this tool. A single id is fine."
}
},
"additionalProperties": false
}List the scrape endpoints this API implements, or describe one of them. Not needed to read a URL — `scrape` does that for any site. Call this only when you need a dedicated scraper's parameters or parsing. The list is grouped by parser: `json_supported` endpoints have a dedicated parser (and take the AI parser too), `json_supported_only_with_prompt_or_schema` ones take only the AI parser, `json_not_supported` ones return no JSON at all. The batch endpoints listed under /v1/async/scrape/batch/ are used for you: give `run_scraper` a list instead. Call this before assuming a dedicated scraper does or does not exist for a site, then call it again with the endpoint name to get the JSON Schema of what that endpoint accepts: types, `required`, `enum` values and defaults. That is the authoritative parameter list — more current than any documentation. Run the endpoint itself with `run_scraper`.
| Argument | Type | Description |
|---|---|---|
| endpoint | any | Name a scrape endpoint to get the JSON Schema of its request body instead of the list. Omit it to list what exists. |
{
"type": "object",
"properties": {
"endpoint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"examples": [
"scrape/amazon/search"
],
"description": "Name a scrape endpoint to get the JSON Schema of its request body instead of the list. Omit it to list what exists."
}
},
"additionalProperties": false
}Read a long page of a result in parts, from where its reply cut it short. Also reads a `search_companies` list that was cut to fit: that has one page, `page=0`, and no other page exists for it. Use the `request_id`, `page` and `next_offset` that a summary, a cut page or the previous part gave, and keep calling with the `next_offset` each part returns until `eof` is true — and stop as soon as you have what you need rather than reading the whole page by reflex. Reading runs no new scrape: the page comes from disk where this server wrote it, or from the API, which keeps the results of queued requests. Returns `text` plus `offset`, `returned_chars`, `total_chars`, `next_offset` and `eof`.
| Argument | Type | Description |
|---|---|---|
| page | integer | Which page of the result, counting from 0. Most results have one; a request for several pages of results, a search say, has more. A `search_companies` list is always page 0. |
| length | integer | Most characters to return; fewer come back if they would not fit. |
| offset | integer | Character to start at: the `next_offset` a summary, a cut page or the previous part gave. |
| request_id* | string | The `request_id` of the result to read. |
{
"type": "object",
"required": [
"request_id"
],
"properties": {
"page": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Which page of the result, counting from 0. Most results have one; a request for several pages of results, a search say, has more. A `search_companies` list is always page 0."
},
"length": {
"type": "integer",
"default": 40000,
"minimum": 1,
"description": "Most characters to return; fewer come back if they would not fit."
},
"offset": {
"type": "integer",
"default": 0,
"minimum": 0,
"description": "Character to start at: the `next_offset` a summary, a cut page or the previous part gave."
},
"request_id": {
"type": "string",
"description": "The `request_id` of the result to read."
}
},
"additionalProperties": false
}Run a dedicated scrape endpoint with its own parameters. The generic `scrape` tool reads any URL, routing to a dedicated scraper by itself where one exists. Use this when at least one of these holds: you need parameters `scrape` lacks (pagination, sort order, store or delivery location and the like), or you need the content a dedicated parser returns structured, described below. Dedicated scrapers exist only for major sites (big search engines, marketplaces, retailers, video platforms and AI chats); most sites have none. Look the endpoint up with `list_scrapers()`, read its parameters with `list_scrapers(endpoint)`, then call it here. An endpoint with a dedicated parser returns its parsed JSON by default; set `output` in `params` (e.g. ["markdown"]) to read the page instead. Other endpoints return Markdown wherever they offer it, unless `output` says otherwise; for structured data from them, describe the fields in `json_prompt`. Endpoints with a dedicated parser return typical page content in a predefined shape: search results (organic links, ads, images, news, videos, SERP extras), product listings and details (title, price, stock, seller, reviews), seller profiles, bestsellers, hotel offers, AI chat answers (prompt, response, citations), YouTube video and channel metadata. That runs first; with no dedicated parser, or one that failed or returned nothing, the AI parser extracts what `json_prompt` describes. The result's `parser` says which one answered, and `parser_note` carries the dedicated parser's own verdict (e.g. PARSE_PARTIAL_SUCCESS_SOME_FIELDS_DEFAULT). If a dedicated result lacks what you need, call again with `parser="ai"`. To run several URLs or queries with the same parameters, give `url` or `query` in `params` as a list: a few run side by side, more go to the endpoint's batch in one request, and the call waits for them. The reply has an item per URL or query, as `scrape` gives for a list. A batch cannot fall back from the dedicated parser to the AI parser item by item: run the ones it failed again with `parser="ai"`. Calls run synchronously. One that times out is sent to the corresponding asynchronous endpoint (`/v1/async/...`) and returns a `request_id` to collect with `check_requests`; an `async/...` endpoint, or one `list_scrapers` lists only in async form, is always queued.
| Argument | Type | Description |
|---|---|---|
| params* | object | The endpoint's own request body. Get its JSON Schema from `list_scrapers(endpoint)` rather than guessing the keys. Give `url` or `query` as a list to run several that share every other parameter. |
| parser | string | auto uses the endpoint's dedicated parser when it has one and falls back to the AI parser when that fails or returns nothing. ai goes straight to the AI parser — use it when a dedicated result lacked the fields you need. |
| endpoint* | string | A scrape endpoint path from `list_scrapers`, without the /v1/ prefix, e.g. 'scrape/amazon/search'. |
| structured | boolean | Return parsed JSON instead of page content. Implied by `json_prompt` or `json_schema`, and by an endpoint with a dedicated parser unless `output` in `params` asks for content. The dedicated parser runs first when there is one. |
| json_prompt | any | Fields to pull out as JSON, in plain words: name them and say what shape you want. Used by the AI parser, which runs when the endpoint has no dedicated parser or its dedicated parser did not return them. Pass this or `json_schema`, not both. Leave unset to read the content yourself. |
| json_schema | any | A JSON Schema the AI parser's output must follow, instead of `json_prompt`: the two cannot be combined. Use it when you need the exact same shape off many pages. |
{
"type": "object",
"required": [
"endpoint",
"params"
],
"properties": {
"params": {
"type": "object",
"description": "The endpoint's own request body. Get its JSON Schema from `list_scrapers(endpoint)` rather than guessing the keys. Give `url` or `query` as a list to run several that share every other parameter.",
"additionalProperties": true
},
"parser": {
"enum": [
"auto",
"ai"
],
"type": "string",
"default": "auto",
"description": "auto uses the endpoint's dedicated parser when it has one and falls back to the AI parser when that fails or returns nothing. ai goes straight to the AI parser — use it when a dedicated result lacked the fields you need."
},
"endpoint": {
"type": "string",
"description": "A scrape endpoint path from `list_scrapers`, without the /v1/ prefix, e.g. 'scrape/amazon/search'."
},
"structured": {
"type": "boolean",
"default": false,
"description": "Return parsed JSON instead of page content. Implied by `json_prompt` or `json_schema`, and by an endpoint with a dedicated parser unless `output` in `params` asks for content. The dedicated parser runs first when there is one."
},
"json_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"examples": [
"Parse the product title, price, and a list of image links"
],
"description": "Fields to pull out as JSON, in plain words: name them and say what shape you want. Used by the AI parser, which runs when the endpoint has no dedicated parser or its dedicated parser did not return them. Pass this or `json_schema`, not both. Leave unset to read the content yourself."
},
"json_schema": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "A JSON Schema the AI parser's output must follow, instead of `json_prompt`: the two cannot be combined. Use it when you need the exact same shape off many pages."
}
},
"additionalProperties": false
}Fetch and read web pages, including JavaScript-heavy and bot-protected ones. Use whenever you have a URL and need what is on it. Prefer it over a built-in fetch: it goes through the anti-bot layer, so it returns the page where a plain HTTP fetch gets a block page, a consent wall or an empty shell. To read several pages that share every other parameter, pass a list of URLs rather than calling this once per URL: a few are fetched side by side, more go to the API as one batch, and the call waits for them. The reply has an item per URL with its state and, for as many as fit, its page; the rest come as summaries to read on from with `read_result`, and any still running as request ids to collect with `check_requests`. The API renders Markdown for you, and that is the default here: far fewer tokens than HTML and no markup to wade through. Try it without `run_js` first. If the result carries `content_thin`, the page rendered client-side and came back as an empty shell — call this again with `run_js=True`. Rendering is slow; when it outlives the synchronous call the request is queued, and you get a request id to collect with `check_requests` instead of the content. `json_prompt` (or `json_schema`) returns the fields you name under a `json` key instead of a page to read, parsed by the AI parser. When you need parameters this tool lacks (pagination, sort order, store or delivery location and the like), or the content a dedicated parser returns structured — results, products, sellers, hotels, questions and answers and the like — `run_scraper` on the site's dedicated scraper is the better fit, where the site has one. Very large pages are not returned whole. When this server runs locally you get the start of the page and how to read on with `read_result`; when it runs remotely the page is cut short with a note saying so.
| Argument | Type | Description |
|---|---|---|
| url* | any | Absolute http(s) URL of the page to read, or a list of URLs to read several pages that share every other parameter in one call. |
| device | any | Viewport to fetch as. The API's default is desktop. |
| format | string | markdown to read the page — far fewer tokens, structure intact. html only when you need the markup itself: attributes, embedded JSON-LD. screenshot for a PNG of the rendered page; it always renders with JavaScript. Ignored when `json_prompt` or `json_schema` is set. |
| run_js | boolean | Execute the page's JavaScript. Needed for pages that render client-side and arrive empty otherwise. Slow: if the render outlives the synchronous call it is queued, and you get a request id to collect with `check_requests` instead of the content. Try without it first. |
| location | any | Two-letter country code to fetch the page from. Use it when the page varies by country — pricing, availability, language. |
| json_prompt | any | Fields to pull out as JSON, in plain words: name them and say what shape you want. Used by the AI parser, which runs when the endpoint has no dedicated parser or its dedicated parser did not return them. Pass this or `json_schema`, not both. Leave unset to read the content yourself. |
| json_schema | any | A JSON Schema the AI parser's output must follow, instead of `json_prompt`: the two cannot be combined. Use it when you need the exact same shape off many pages. |
{
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Absolute http(s) URL of the page to read, or a list of URLs to read several pages that share every other parameter in one call."
},
"device": {
"anyOf": [
{
"enum": [
"desktop",
"mobile"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Viewport to fetch as. The API's default is desktop."
},
"format": {
"enum": [
"markdown",
"html",
"screenshot"
],
"type": "string",
"default": "markdown",
"description": "markdown to read the page — far fewer tokens, structure intact. html only when you need the markup itself: attributes, embedded JSON-LD. screenshot for a PNG of the rendered page; it always renders with JavaScript. Ignored when `json_prompt` or `json_schema` is set."
},
"run_js": {
"type": "boolean",
"default": false,
"description": "Execute the page's JavaScript. Needed for pages that render client-side and arrive empty otherwise. Slow: if the render outlives the synchronous call it is queued, and you get a request id to collect with `check_requests` instead of the content. Try without it first."
},
"location": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
{
"type": "null"
}
],
"default": null,
"examples": [
"DE",
"US",
"LT"
],
"description": "Two-letter country code to fetch the page from. Use it when the page varies by country — pricing, availability, language."
},
"json_prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"examples": [
"Parse the product title, price, and a list of image links"
],
"description": "Fields to pull out as JSON, in plain words: name them and say what shape you want. Used by the AI parser, which runs when the endpoint has no dedicated parser or its dedicated parser did not return them. Pass this or `json_schema`, not both. Leave unset to read the content yourself."
},
"json_schema": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "A JSON Schema the AI parser's output must follow, instead of `json_prompt`: the two cannot be combined. Use it when you need the exact same shape off many pages."
}
},
"additionalProperties": false
}Search the live web and return ranked organic results. Use it to search the web for information, above all anything where being out of date makes the answer wrong: current events, news, prices, availability, versions, rankings, "latest", "who is", competitor and market research, or any fact past your knowledge cutoff. Prefer it over a built-in web search and over answering from memory. Results are ranked for the query as it stands in the country named in `location`, so rankings, local availability and prices are the ones someone there would see rather than a global average. Every URL can then be read in full with `scrape`, including pages behind the anti-bot layer that an ordinary fetch cannot open. Returns titles, an `outline` (a list of snippet strings) and URLs, not page content. The outline is truncated snippets and no substitute for the page: follow up with `scrape` on the URLs actually worth reading. Not for local files, git, or anything off the public web.
| Argument | Type | Description |
|---|---|---|
| query* | string | What to search for, as a natural search phrase. Keyword-shaped queries beat sentence-shaped ones. One question per search. |
| location | any | ISO 3166-1 alpha-2 country code to rank results for. Pass it whenever the answer is geographic. A place name such as "Germany" is rejected. |
| max_results | integer | Maximum number of results to return. The response may contain fewer. |
{
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"examples": [
"eu ai act compliance deadlines",
"figma pricing per seat"
],
"maxLength": 2048,
"minLength": 1,
"description": "What to search for, as a natural search phrase. Keyword-shaped queries beat sentence-shaped ones. One question per search."
},
"location": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
{
"type": "null"
}
],
"default": null,
"examples": [
"DE",
"US",
"LT"
],
"description": "ISO 3166-1 alpha-2 country code to rank results for. Pass it whenever the answer is geographic. A place name such as \"Germany\" is rejected."
},
"max_results": {
"type": "integer",
"default": 10,
"maximum": 20,
"minimum": 1,
"description": "Maximum number of results to return. The response may contain fewer."
}
},
"additionalProperties": false
}Search for companies and return their profiles, best match first. Use it to look up a company by name, or to find companies matching a description (an industry, a product, a place, a size): market and competitor mapping, lead lists, funding research. Prefer it over `search` plus `scrape` when the answer is a company's facts rather than a web page. A profile can carry the website and LinkedIn URLs, description, industry, founding year, employee count, headquarters, funding, annual revenue and web traffic; any field may be missing. The figures are often estimates and not necessarily current: check one that matters on the company's own website with `scrape`. There are no location or filter parameters: describe the whole set you want in one `query`.
| Argument | Type | Description |
|---|---|---|
| query* | string | A company name or a free-text description of the companies wanted. Say what they do, where and how big, in words. |
| max_results | integer | Maximum number of companies to return. Profiles are long: ask for what you will use. The response may contain fewer. |
{
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"examples": [
"electric vehicle battery makers in Germany",
"Figma"
],
"maxLength": 2000,
"minLength": 1,
"description": "A company name or a free-text description of the companies wanted. Say what they do, where and how big, in words."
},
"max_results": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "Maximum number of companies to return. Profiles are long: ask for what you will use. The response may contain fewer."
}
},
"additionalProperties": false
}We read every tool's name, description and inputs the way the model will, looking for instructions hidden from you. A clean result means no warning signs, not a guarantee. Scanned Nov 20, 2026.