Skip to content
Browsa
Sign in Get an API key
  1. Guides
  2. MCP server

Set up the Browsa MCP server in Claude, Cursor and VS Code.

The Browsa MCP server (@browsa/mcp) is a Model Context Protocol server that gives an AI assistant a real Chromium browser in the cloud. You ask in plain language, a browser agent on Browsa does the work, and the assistant gets the answer back with a link to watch the browser live.

Time
About 2 minutes
Needs
Node.js 18 or later, a Browsa API key
Package
@browsa/mcp on npm, MIT

What is a browser MCP server?

MCP is an open protocol that lets an AI app call tools from outside the model. A browser MCP server adds tools that open web pages, click, type and read, so the assistant can use websites that have no API. The Browsa server runs those steps in a cloud browser rather than on your machine, which means your own browser, cookies and passwords are never touched, and the work keeps running even if the page is slow.

The server itself is a small Node.js process that your MCP client starts with npx. Every request it sends goes to the Browsa API with your agt_live_ key.

  1. Get an API key

    Sign up and copy your key from Keys in the dashboard. You get 100 free credits once you verify your email, no card.

  2. Add the server to your client

    Claude Desktop

    Open the config file: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows. Add the server, save and restart Claude Desktop.

    claude_desktop_config.json
    {
  "mcpServers": {
    "browsa": {
      "command": "npx",
      "args": ["-y", "@browsa/mcp"],
      "env": {
        "BROWSA_API_KEY": "agt_live_..."
      }
    }
  }
}

    Claude Code

    Add it from the terminal. Put the server name before -e, and everything after -- is the command Claude Code runs.

    Terminal
    claude mcp add browsa -e BROWSA_API_KEY=agt_live_... -- npx -y @browsa/mcp

    Run claude mcp list to check that it connected.

    Cursor

    Add the same block to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project.

    ~/.cursor/mcp.json
    {
  "mcpServers": {
    "browsa": {
      "command": "npx",
      "args": ["-y", "@browsa/mcp"],
      "env": { "BROWSA_API_KEY": "agt_live_..." }
    }
  }
}

    VS Code

    VS Code reads .vscode/mcp.json in your workspace. Its format uses servers instead of mcpServers. This version asks for the key the first time the server starts, so the key is not saved in the file.

    .vscode/mcp.json
    {
  "inputs": [
    {
      "type": "promptString",
      "id": "browsa-api-key",
      "description": "Browsa API key (agt_live_...)",
      "password": true
    }
  ],
  "servers": {
    "browsa": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@browsa/mcp"],
      "env": { "BROWSA_API_KEY": "${input:browsa-api-key}" }
    }
  }
}

    Cline, Continue, Zed and other clients

    Any client that starts MCP servers over stdio works. Point it at npx -y @browsa/mcp and set BROWSA_API_KEY in the server's environment.

  3. Try it

    Ask your assistant something that needs a live web page, for example:

    • "Go to news.ycombinator.com and tell me the top story."
    • "Open books.toscrape.com and list the first five books with their prices."
    • "Every morning, check the price on this product page and send the result to my webhook."

    The assistant calls run_task. The result comes back with a live_url: open it to watch the browser, and use the mouse and keyboard if a page needs a person.

Which model runs the browser task?

The browser agent needs a language model. You do not need to put a model key in the config. For each call, the first match wins:

  1. llm: "browsa" on the callBrowsa's hosted model, no key, 5 extra credits per task.
  2. BROWSA_LLM_API_KEYYour Anthropic, OpenAI or Google key, sent with each task, encrypted while the task runs and deleted when it ends.
  3. BROWSA_LLM_KEY_IDA key you saved in the dashboard, by id.
  4. Nothing setThe workspace's default saved key. With no saved key and no model named, the task runs on Browsa's hosted model and the result says so.

BROWSA_LLM sets a default model, for example anthropic:claude-sonnet-5-5. If you name a model and no key is available, the tool returns LLM_KEY_REQUIRED instead of falling back.

What tools does the assistant get?

run_task
Runs a browser task described in plain language and returns the result and a live view link.
get_job
Checks on a long-running task, optionally waiting on the server.
cancel_job
Cancels a running task.
respond_to_job
Answers a task that stopped to ask for input.
list_job_files
Lists the files a task wrote, such as downloaded reports.
create_schedule, list_schedules
Recurring tasks, from every hour to every 30 days.
list_webhooks, create_webhook, delete_webhook
Where results are delivered, as HMAC-signed webhooks.
list_identities
Persistent identities whose saved logins a task can reuse.
list_llm_keys
Saved model keys, masked. It never returns a secret.
credits
Credit balance and packs.

What does it cost?

The MCP server is free. Each run_task is an agent task, billed in credits: its browser time (1 credit per started 12 minutes), plus 1 credit, plus 1 credit for every 5 steps. Browsa's hosted model adds 5 credits.

Task (finishes inside 12 minutes)Your own model keyBrowsa's hosted model
10 steps4 credits9 credits
20 steps6 credits11 credits

A task that fails gets its browser charge back and is not charged for steps. With your own key, your model provider bills you for tokens; Browsa adds no markup. One credit is $0.10 on the $20 Starter pack. Full pricing.

Troubleshooting

The server does not show up

Restart the client after editing its config, check that the JSON is valid, and run node --version in a terminal: the server needs Node.js 18 or later and npx on the path the client uses.

LLM_KEY_REQUIRED

You named a model but no key is available for it. Save a key at dashboard/llm-keys, set BROWSA_LLM_API_KEY, or ask for llm: "browsa".

402 INSUFFICIENT_CREDIT or BUDGET_REACHED

The balance is too low, or your monthly spending limit is reached. Ask the assistant to run the credits tool, or check the Credits page in the dashboard.

Questions

Does the browser run on my computer?

No. The MCP server is a small Node.js process on your machine that calls the Browsa API. The browser runs in Browsa's cloud, so nothing else needs to be installed and your own browser is never touched.

Do I need an Anthropic or OpenAI key?

No. With only BROWSA_API_KEY set and no saved key, tasks run on Browsa's hosted model for 5 extra credits each, and the server says so in the result. To use your own model, save an Anthropic, OpenAI or Google key in the dashboard, or set BROWSA_LLM_API_KEY.

What does each request cost?

Each run_task call is an agent task: its browser time (1 credit per started 12 minutes), plus 1 credit, plus 1 credit for every 5 steps. A 10-step task that finishes inside 12 minutes costs 4 credits with your own key and 9 on Browsa's hosted model. The MCP server itself is free.

Which MCP clients does it work with?

Any client that can start a local MCP server over stdio, including Claude Desktop, Claude Code, Cursor, VS Code, Cline, Continue and Zed. The server needs Node.js 18 or later for npx.

Next steps

A real browser for Claude and Cursor

What people use the MCP server for, with pricing.

Agent task reference

The API behind run_task: structured output, allowed domains, saved credentials.

Drive the browser from your own code

Connect Playwright or Puppeteer to a Browsa browser over CDP.

Give your assistant a browser.

100 free credits. No card, no subscription.

Get an API key All guides