Web Api Mcp
Self-hostable MCP server for the Oxylabs Web API
mcp-name: io.oxylabs/web-api-mcp
This repository is a developer-focused, technical reference covering the official Model Context Protocol server for the Oxylabs Web API. It gives any MCP-capable agent live web access – search, scrape pages as Markdown or JSON, and call dedicated scrapers – through one MCP connection.
| Remote MCP | Self-hosted MCP | |
|---|---|---|
| Runs on | Oxylabs infrastructure | Your machine or infrastructure |
| Setup | Add the server URL and your API key to your client | Install the server (Python 3.10+ and uv), then configure your client |
| Updates and maintenance | Managed by Oxylabs | Managed by you |
| Best for | The quickest way to give a compatible agent access to Web API | Full control over the environment, or clients that can't connect to remote servers with a custom header |
The tools and their behavior are the same on both options, and the sections on self-hosting cover everything you need to run the server yourself.
| Tool | What it does |
|---|---|
search |
Search the live web, returns ranked organic results (title, outline snippets, URL) |
scrape |
Read a URL, or a list of URLs, as Markdown by default, including JS-heavy and bot-protected pages. Ask for a screenshot, or pass json_prompt / json_schema to pull named fields off the page as JSON |
list_scrapers |
List the scrape endpoints the API implements, grouped by parser support, or describe one's parameters |
run_scraper |
Run a dedicated scrape endpoint with its own parameters, as content or as structured JSON; a list of urls or querys runs them all |
check_requests |
Collect requests the API is running in the background, waiting for them to finish |
read_result |
Read a page too long for one reply in parts, by its request id |
All six are annotated readOnlyHint — nothing here writes anything, so clients can run
them without prompting.
Requirements
- An Oxylabs Web API key — in the Oxylabs dashboard, create a Web API instance, open it, and copy the API key shown at the top of the instance page.
- For Remote MCP – an MCP client that supports remote (HTTP) MCP servers with custom headers, such as Claude Code, Codex, or Cursor.
- For self-hosting – Python 3.10+ (built on FastMCP, installed with the package) and
uv.
Connect to the Remote MCP server
The server is hosted and maintained by Oxylabs. There is nothing to install or update.
https://mcp.oxylabs.io/web-api-mcp
The server authenticates each request with your Web API key, sent as an Authorization: Bearer <key> header. Set the key as an environment variable in the terminal where you run your client:
export OXYLABS_WEB_API_KEY="your_api_key_here"
Claude Code:
claude mcp add --transport http --scope user oxylabs-web-api \
https://mcp.oxylabs.io/web-api-mcp \
--header "Authorization: Bearer ${OXYLABS_WEB_API_KEY}"
Codex:
codex mcp add oxylabs-web-api \
--url https://mcp.oxylabs.io/web-api-mcp \
--bearer-token-env-var OXYLABS_WEB_API_KEY
Cursor — one click, then make the key visible to Cursor (below):
From the project's README.