Create a browser agent

Set up an agent that drives a real browser. There are two ways in, and which one you want depends on where the agent lives.

Use MCP when the agent is an assistant someone talks to, such as Claude, Cursor, or VS Code. The client keeps its own loop, and Browserless supplies the browser tools.

Use the Agent Run API when your own code needs a task done. You send the task in plain English, Browserless runs both the browser and the model, and you poll for the result.

Set up MCP in your AI client

1. Get Your API Token

   Sign up for a free account, then copy your API token from the account dashboard.

   Clients that support OAuth can skip this and sign in to Browserless when they first connect.

2. Add the Server to Your Client

   The hosted server is https://mcp.browserless.io/mcp. There's nothing to install.

   Claude Code

   claude mcp add --transport http browserless https://mcp.browserless.io/mcp \
     --header "Authorization: Bearer YOUR_API_TOKEN_HERE"

   Claude Desktop

   Add to claude_desktop_config.json:

   {
     "mcpServers": {
       "browserless": {
         "type": "http",
         "url": "https://mcp.browserless.io/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_TOKEN_HERE"
         }
       }
     }
   }

   Cursor

   Add to your Cursor MCP settings:

   {
     "mcpServers": {
       "browserless": {
         "type": "http",
         "url": "https://mcp.browserless.io/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_TOKEN_HERE"
         }
       }
     }
   }

   Claude.ai

   The custom connector form takes a URL only, so the token goes in the query string:

   https://mcp.browserless.io/mcp?token=YOUR_API_TOKEN_HERE

   Add it under Customize > Connectors > Add custom connector.

   Other clients, including VS Code and Windsurf, are in MCP server setup.

3. Give the Agent a Task

   Restart the client so it picks up the server, then ask for something that needs a browser:

   Open news.ycombinator.com and give me the titles of the top three stories.

   The client picks the tool itself. For multi-step work such as signing in or paginating, it reaches for browserless_agent, which holds one browser session across turns so cookies and history survive between tool calls.

Set up the Agent Run API

BETA

The Agent Run API is currently in beta. Parameters and response shapes may change in future releases.

The Agent Run API is only available for Cloud plans. Contact us for more information.

1. Get Your API Token

   Copy your API token from the account dashboard. You don't need a model key: Browserless runs the browser and the model.

2. Start a Run

   POST /agent/run takes the task in plain English and returns a run ID immediately. The agent works in the background.

   cURL

   curl --request POST \
     --url 'https://production-sfo.browserless.io/agent/run?token=YOUR_API_TOKEN_HERE' \
     --header 'Content-Type: application/json' \
     --data '{
     "query": "Go to https://example.com and tell me the exact text of the top-level heading."
   }'

   JavaScript

   const TOKEN = "YOUR_API_TOKEN_HERE";
   
   const response = await fetch(
     `https://production-sfo.browserless.io/agent/run?token=${TOKEN}`,
     {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         query:
           "Go to https://example.com and tell me the exact text of the top-level heading.",
       }),
     }
   );
   
   const { id } = await response.json();
   console.log(id);

   Python

   import requests
   
   TOKEN = "YOUR_API_TOKEN_HERE"
   
   response = requests.post(
       f"https://production-sfo.browserless.io/agent/run?token={TOKEN}",
       json={
           "query": "Go to https://example.com and tell me the exact text of the top-level heading."
       },
   )
   
   print(response.json()["id"])

   Response

   {
     "id": "run_abc123def456",
     "status": "pending"
   }

   The query must be at least 10 characters.

3. Poll for the Result

   Request the run until status reaches a terminal value: succeeded, failed, timed_out, or stopped. Each poll also returns the steps taken so far, so you can show progress instead of a spinner.

   cURL

   curl --request GET \
     --url 'https://production-sfo.browserless.io/agent/run/run_abc123def456?token=YOUR_API_TOKEN_HERE'

   JavaScript

   const TOKEN = "YOUR_API_TOKEN_HERE";
   const runId = "run_abc123def456";
   const TERMINAL = ["succeeded", "failed", "timed_out", "stopped"];
   
   while (true) {
     const response = await fetch(
       `https://production-sfo.browserless.io/agent/run/${runId}?token=${TOKEN}`
     );
     const result = await response.json();
     console.log(result.status, result.steps?.at(-1) ?? "");
   
     if (TERMINAL.includes(result.status)) {
       console.log(result.data);
       break;
     }
   
     // A request right after submitting returns pending, so poll on an interval.
     await new Promise((resolve) => setTimeout(resolve, 3000));
   }

   Python

   import time
   import requests
   
   TOKEN = "YOUR_API_TOKEN_HERE"
   run_id = "run_abc123def456"
   url = f"https://production-sfo.browserless.io/agent/run/{run_id}?token={TOKEN}"
   TERMINAL = {"succeeded", "failed", "timed_out", "stopped"}
   
   while True:
       result = requests.get(url).json()
       print(result["status"], (result.get("steps") or [""])[-1])
   
       if result["status"] in TERMINAL:
           print(result["data"])
           break
   
       # A request right after submitting returns pending, so poll on an interval.
       time.sleep(3)

   Response

   {
     "id": "run_abc123def456",
     "status": "succeeded",
     "data": {
       "answer": "The exact text of the top-level heading is: Example Domain"
     },
     "error": null,
     "steps": [
       "Opening the example homepage",
       "Reading the main heading",
       "Closing the completed browser session"
     ]
   }

   data is { "answer": "..." } unless you pass a responseSchema, which shapes it to match. Results are kept for 7 days.

FAQ & Troubleshooting

My MCP client doesn't list the Browserless tools.

Restart the client after editing its config. If they still don't appear, check that the config uses "type": "http" and that the token is on the Authorization header as Bearer YOUR_API_TOKEN_HERE. The query-string form is only for Claude.ai's connector field, which accepts a URL and nothing else.

A run came back timed_out.

The task was too broad, or the site was too slow. Narrow it, give the agent a starting URL, and say what a finished answer looks like. "Find the pricing" invites wandering. "Open this URL and return the monthly price of each plan" doesn't.

Can I constrain where the agent goes, or what it returns?

Yes. POST /agent/run accepts a starting URL, a navigation allowlist, an authentication profile, and a responseSchema for the shape of the answer. See the Agent Run API reference.

Do I need my own model API key?

Not for either path here. The Agent Run API manages the model for you, and with MCP the client you're already using brings its own.

Next steps

Agent Run API

Output schemas, allowlists, webhooks, and polling

Browser Agent tool

The stateful snapshot protocol behind MCP browsing

MCP overview

Both Browserless MCP servers, and what each one is for