MCP Server

What is MCP? #

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools. Instead of just generating text, the agent can take real actions — browse the web, fill forms, extract data.

The Browserbeam MCP Server exposes 19 tools that give your AI agent a real browser session. The agent decides which tool to call and when. You just describe what you want.

Setup for Cursor #

Add this to your ~/.cursor/mcp.json file. Create it if it doesn't exist.

{
  "mcpServers": {
    "browserbeam": {
      "command": "npx",
      "args": ["-y", "@browserbeam/mcp-server"],
      "env": {
        "BROWSERBEAM_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Cursor. The Browserbeam tools appear in the MCP tools list automatically.

Setup for Claude Desktop #

Open the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Browserbeam server to the mcpServers object:

{
  "mcpServers": {
    "browserbeam": {
      "command": "npx",
      "args": ["-y", "@browserbeam/mcp-server"],
      "env": {
        "BROWSERBEAM_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You'll see the Browserbeam tools in the tool picker.

Setup for Windsurf #

Add this to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "browserbeam": {
      "command": "npx",
      "args": ["-y", "@browserbeam/mcp-server"],
      "env": {
        "BROWSERBEAM_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Windsurf. The tools are available immediately.

Available Tools #

The MCP server exposes 19 tools. Your AI agent picks which tool to call based on your instructions.

How It Works #

When you ask your AI agent to do something in a browser, the flow looks like this:

1. You describe a task in natural language. The AI agent decides which tool to use.
2. The agent calls a Browserbeam tool through MCP (e.g. browserbeam_create_session).
3. The MCP server sends the request to the Browserbeam API over HTTPS.
4. Browserbeam spins up a real Chromium browser and executes the action.
5. The API returns structured data: page content as markdown, element refs, extracted data, or screenshots.
6. The agent reads the response, reasons about the result, and decides the next step.

Example Conversation #

Here's how an AI agent uses the tools in sequence. You say "Search Hacker News for posts about browser automation." The agent handles the rest.

{
  "tool": "browserbeam_create_session",
  "params": {
    "url": "https://news.ycombinator.com/"
  }
}

{
  "tool": "browserbeam_extract",
  "params": {
    "session_id": "ses_abc123",
    "schema": "{\"stories\": [{\"_parent\": \".titleline\", \"title\": \"a >> text\", \"url\": \"a >> href\"}]}"
  }
}

{
  "tool": "browserbeam_fill",
  "params": {
    "session_id": "ses_abc123",
    "fields": {"q": "browser automation"},
    "submit": true
  }
}

{
  "tool": "browserbeam_screenshot",
  "params": {
    "session_id": "ses_abc123"
  }
}

{
  "tool": "browserbeam_close",
  "params": {
    "session_id": "ses_abc123"
  }
}

The agent responds with a summary of the top results about browser automation from Hacker News. Five tool calls, zero code written by you.

Environment Variables #

Troubleshooting #