# Hyperbrowser — how to use (mcp.ai)

Connect your Hyperbrowser account and use 43 tools for web scraping straight from your AI agent. Connect with your own API key. Hyperbrowser is a next-generation platform empowering AI agents and enabling effortless, scalable browser automation.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_hyperbrowser?ms=1787295660000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `hyperbrowser_add_extension`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/hyperbrowser`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/hyperbrowser/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/hyperbrowser/add/extension` — Tool to add a new browser extension to Hyperbrowser for use in sessions. Use when you need to upload a Chrome extension zip file that can be loaded into browser sessions. The extension zip must contai
  - body: { file: object, name?: string }
- `POST https://api.mcp.ai/api/hyperbrowser/create/profile` — Creates a new persistent Hyperbrowser profile for storing browser state (cookies, sessions, etc.). Use this to create a reusable profile that can be attached to browser sessions via the profile ID. Pr
  - body: { name?: string }
- `POST https://api.mcp.ai/api/hyperbrowser/create/scrape/job` — Tool to initiate a new scrape job. Use when you need to extract structured content from a target URL with custom session and scrape settings.
  - body: { url: string, scrapeOptions?: object, sessionOptions?: object }
- `POST https://api.mcp.ai/api/hyperbrowser/create/session` — Tool to create a new browser session with custom stealth, proxy, and privacy settings. Use when initializing an automated browsing session with specific configuration.
  - body: { device?: string[], region?: string, screen?: object, adblock?: boolean, locales?: string[], profile?: object, platform?: string[], trackers?: boolean, useProxy?: boolean, proxyCity?: string, annoyances?: boolean, proxyState?: string, staticIpId?: string, useStealth?: boolean, browserArgs?: string[], proxyServer?: string, extensionIds?: string[], proxyCountry?: string, urlBlocklist?: string[], acceptCookies?: boolean, saveDownloads?: boolean, solveCaptchas?: boolean, timeoutMinutes?: integer, useUltraStealth?: boolean, operatingSystems?: string[], viewOnlyLiveView?: boolean, enableWebRecording?: boolean, imageCaptchaParams?: object[], enableWindowManager?: boolean, proxyServerPassword?: string, proxyServerUsername?: string, disablePasswordManager?: boolean, enableVideoWebRecording?: boolean, enableWindowManagerTaskbar?: boolean, enableAlwaysOpenPdfExternally?: boolean, disablePostQuantumKeyAgreement?: boolean }
- `POST https://api.mcp.ai/api/hyperbrowser/delete/profile` — Tool to delete a profile. Use when you need to remove a profile by its unique identifier after confirming its existence.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/fetch/web/page` — Tool to fetch a web page and return content in various formats (HTML, Markdown, JSON, screenshot, etc.). Use when you need to retrieve and process web content with customizable browser settings, outpu
  - body: { url: string, cache?: object, browser?: object, outputs?: object, stealth?: string, navigation?: object }
- `POST https://api.mcp.ai/api/hyperbrowser/get/browser/use/task/result` — DEPRECATED: Use HYPERBROWSER_GET_BROWSER_USE_TASK_STATUS instead. Tool to retrieve the status and results of a browser use task. Use after starting a browser use task to check its progress, retrieve e
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/browser/use/task/status` — Tool to retrieve the current status of a browser-use task. Use when checking if a browser automation task has completed or is still pending.
  - body: { task_id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/claude/computer/use/task/result` — Tool to retrieve the complete result and status of a Claude Computer Use task. Use when you need full task details including execution steps, final results, and error information.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/claude/computer/use/task/status` — Poll the execution status of a Claude Computer Use task. Use after calling HYPERBROWSER_START_CLAUDE_COMPUTER_USE_TASK to check if the task has completed, is still running, or has failed. Pass the job
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/crawl/job/status` — Tool to retrieve the status and results of a specific crawl job. Use after submitting a crawl job to check its progress or fetch results.
  - body: { job_id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/crawl/status` — Tool to retrieve the current status of a specific crawl job. Use after initiating a crawl job to poll its status.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/cua/task/result` — Tool to retrieve the status and results of a CUA (Claude User Agent) task. Use after starting a CUA task to check its progress, retrieve execution steps, and obtain the final result.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/cua/task/status` — Poll the execution status of a CUA task. Use to check if a CUA task has completed, is still running, or has failed.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/extract/job/result` — Tool to fetch the status and results of a specific extract job. Use after initiating an extract job to monitor progress and retrieve final data.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/extract/job/status` — Retrieve the status of an extract job. Use after calling Start Extract Job to poll its progress. Poll periodically until status is 'completed' or 'failed', then use Get Extract Job Result to retrieve 
  - body: { job_id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/gemini/computer/use/task/result` — Tool to retrieve the current status and results of a Gemini Computer Use task. Use when checking if a Gemini automation task has completed or is still pending.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/hyper/agent/task/result` — Tool to retrieve the status and results of a HyperAgent task. Use when checking if a HyperAgent task has completed or to get the final results and execution steps.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/profile` — Retrieves details of a specific Hyperbrowser profile by its UUID. Returns profile metadata including name, team association, and timestamps. Use the List Profiles action first to obtain valid profile 
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/scrape/job/result` — Retrieves the status and results of a scrape job. Poll this endpoint after creating a scrape job to check progress and get the scraped content when completed. Returns jobId, status (pending/running/co
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/scrape/job/status` — Tool to retrieve the current status of a specific scrape job. Use after initiating a scrape job to poll its status; poll at moderate intervals (e.g., every 2–5 seconds) rather than tight loops to avoi
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/session/details` — Retrieve detailed information about a Hyperbrowser session by its ID. Use this tool to get connection endpoints (wsEndpoint, liveUrl), session status, and configuration details for an existing session
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/session/downloads/url` — Tool to retrieve the downloads URL for a session. Returns a signed URL to download files saved during a browser session. Note: The session must be created with 'saveDownloads: true' for downloads to b
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/session/recording` — Retrieve the recording URL for a browser session. Returns a pre-signed S3 URL to download the rrweb JSON recording. The recording status indicates availability: - 'pending': Recording is being prepare
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/session/video/recording/url` — Tool to retrieve the video recording URL for a browser session. Returns a pre-signed URL to download the video recording. The video recording status indicates availability: - 'pending': Video recordin
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/get/web/crawl/result` — Tool to retrieve the status and results of a web crawl job. Use after submitting a web crawl job to check its progress and fetch paginated results. Supports pagination via page and batchSize parameter
  - body: { id: string, page?: integer, batchSize?: integer }
- `POST https://api.mcp.ai/api/hyperbrowser/get/web/crawl/status` — Tool to retrieve just the status of a web crawl job without the full results. Use after initiating a web crawl to poll its current state.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/list/extensions` — Tool to list all browser extensions. Use when you need to fetch all available extensions for the Hyperbrowser account.
- `POST https://api.mcp.ai/api/hyperbrowser/list/profiles` — Tool to list profiles. Use when you need to fetch paginated profiles and optionally filter by name.
  - body: { name?: string, page?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/hyperbrowser/list/sessions` — Tool to list sessions with optional status filter. Use when you need a paginated overview of browser sessions before acting on them.
  - body: { page?: integer, status?: string }
- `POST https://api.mcp.ai/api/hyperbrowser/search/web` — Tool to perform a web search and retrieve results with titles, URLs, and descriptions. Use when you need to search the web for information on a specific topic or query.
  - body: { page?: integer, query: string, filters?: object, location?: object, maxAgeSeconds?: integer }
- `POST https://api.mcp.ai/api/hyperbrowser/start/browser/use/task` — Tool to start an asynchronous browser-use task. Use when you need to automate web interactions given a task instruction.
  - body: { llm?: string, task: string, apiKeys?: object, maxSteps?: integer, sessionId?: string, useVision?: boolean, plannerLlm?: string, maxFailures?: integer, initialActions?: object[], maxInputTokens?: integer, sessionOptions?: object, validateOutput?: boolean, keepBrowserOpen?: boolean, plannerInterval?: integer, useCustomApiKeys?: boolean, maxActionsPerStep?: integer, pageExtractionLlm?: string, useVisionForPlanner?: boolean }
- `POST https://api.mcp.ai/api/hyperbrowser/start/claude/computer/use/task` — Tool to start a Claude Computer Use task. Use when you need AI-driven automated browser interactions. Call after you have your task prompt and any session preferences configured.
  - body: { llm?: string, task: string, apiKeys?: object, maxSteps?: integer, sessionId?: string, maxFailures?: integer, sessionOptions?: object, keepBrowserOpen?: boolean, useCustomApiKeys?: boolean, useComputerAction?: boolean }
- `POST https://api.mcp.ai/api/hyperbrowser/start/crawl/job` — Tool to start a new crawl job for a specified URL. Use when you need to initiate a web crawl before checking job status.
  - body: { url: string, maxPages?: integer, followLinks?: boolean, ignoreSitemap?: boolean, scrapeOptions?: object, sessionOptions?: object, excludePatterns?: string[], includePatterns?: string[] }
- `POST https://api.mcp.ai/api/hyperbrowser/start/cua/task` — Tool to start an OpenAI CUA (Computer-Using Agent) task. Use when you need AI-driven automated browser interactions powered by OpenAI. Call after you have your task prompt and any session preferences 
  - body: { task: string, apiKeys?: object, maxSteps?: integer, sessionId?: string, maxFailures?: integer, sessionOptions?: object, keepBrowserOpen?: boolean, useCustomApiKeys?: boolean, useComputerAction?: boolean }
- `POST https://api.mcp.ai/api/hyperbrowser/start/extract/job` — Start an AI-powered data extraction job from one or more web pages. Use this tool to scrape structured data from websites by providing URLs and either a natural language prompt describing what to extr
  - body: { urls: string[], prompt?: string, schema?: object, waitFor?: integer, maxLinks?: integer, systemPrompt?: string, sessionOptions?: object }
- `POST https://api.mcp.ai/api/hyperbrowser/start/gemini/computer/use/task` — Tool to start a Gemini Computer Use task for browser automation using Google's Gemini. Use when you need AI-driven automated browser interactions with Gemini models.
  - body: { llm?: string, task: string, apiKeys?: object, maxSteps?: integer, sessionId?: string, maxFailures?: integer, sessionOptions?: object, keepBrowserOpen?: boolean, useCustomApiKeys?: boolean, useComputerAction?: boolean }
- `POST https://api.mcp.ai/api/hyperbrowser/start/web/crawl` — Tool to start an asynchronous web crawl job that follows links from a starting URL and returns content from each page. Use when you need to crawl multiple pages from a website.
  - body: { url: string, cache?: object, browser?: object, outputs?: object, stealth?: string, navigation?: object, crawlOptions?: object }
- `POST https://api.mcp.ai/api/hyperbrowser/stop/browser/use/task` — Tool to stop a running browser-use task. Use when halting an in-progress browser automation task after confirming its task ID.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/stop/claude/computer/use/task` — Tool to stop a running Claude computer use task. Use when a Claude computer use task is in progress and needs to be terminated.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/stop/cua/task` — Tool to stop a running CUA task. Use when a CUA task is in progress and needs to be terminated.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/stop/gemini/computer/use/task` — Tool to stop a running Gemini computer use task. Use when a Gemini computer use task is in progress and needs to be terminated.
  - body: { id: string }
- `POST https://api.mcp.ai/api/hyperbrowser/stop/session` — Tool to stop a running session by ID. Use after confirming the session is active.
  - body: { id: string }

## Example prompts
- "What can I do in Hyperbrowser?"
- "Show me a summary of my Hyperbrowser account"

## More
- Page: https://mcp.ai/hyperbrowser
- Agent spec (llms.txt): https://mcp.ai/hyperbrowser/llms.txt
- Postman collection: https://mcp.ai/hyperbrowser/postman.json