ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Capture a Webpage Screenshot with an AI Agent Using Browserbase MCP

Connect an AI agent to Browserbase MCP, navigate to a webpage, and verify which screenshot tools your server version actually exposes.

By the ScreenshotNeo team4 October 20267 min read

To capture a webpage screenshot with an AI agent using Browserbase MCP, connect your MCP client to Browserbase’s hosted server, authenticate with an API key, and ask the agent to navigate to the page. Then inspect the tools exposed by your server before asking it to capture an image: the current setup documentation lists start, end, navigate, act, observe, and extract, but does not list a screenshot tool. Browserbase’s v3 release notes say the older browserbase_screenshot tool was removed, and the reviewed docs do not identify a replacement invocation.

Browserbase describes its MCP server as cloud browser automation using Browserbase and Stagehand, and its overview mentions screenshot capture as a capability. That broad description does not establish a current MCP screenshot command or schema. You can reliably configure the connection and navigate with the currently documented tools; verify screenshot availability against the tool list exposed by your installed server before relying on a particular call. ScreenshotNeo is a direct screenshot API alternative when you need a documented one-request capture flow.

1. Connect your MCP client to Browserbase

For most users, Browserbase recommends its hosted Streamable HTTP server. The endpoint is https://mcp.browserbase.com/mcp. Tool calls require a Browserbase API key, available from the Browserbase Dashboard. Prefer an authorization header if your MCP client supports custom headers.

The exact configuration shape depends on your MCP client. Use its documented fields for an HTTP MCP server and headers; this JSON illustrates the values to configure, not a universal client-specific config file:

{
  "url": "https://mcp.browserbase.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_BROWSERBASE_API_KEY"
  }
}

Browserbase also accepts the x-bb-api-key header. Use one authentication header as supported by your client:

{
  "url": "https://mcp.browserbase.com/mcp",
  "headers": {
    "x-bb-api-key": "YOUR_BROWSERBASE_API_KEY"
  }
}

The browserbaseApiKey query parameter remains available only as a deprecated compatibility fallback for clients that cannot set headers. Avoid putting secrets in URLs when a header is supported, since URLs can be recorded in logs or diagnostics.

Hosted HTTP or local STDIO?

The hosted endpoint is the recommended starting point and avoids operating the MCP server locally. The official setup documentation also describes local STDIO. Consider local mode when your MCP client requires it or you need to operate/customize a local server; follow the current Browserbase setup instructions for its command and configuration rather than copying an unverified launch command.

2. Refresh the client and inspect available tools

  1. Save the MCP server configuration and add the Browserbase API key using the supported header.
  2. Reload or refresh the MCP client so it reconnects to the server.
  3. Open the client’s connected-server or tool listing and confirm the Browserbase tools are available.
  4. Check the actual tool names and input schemas exposed by that server version. Do this before instructing an agent to use a screenshot tool.

The current setup page lists these six tools:

Tool Documented purpose
start Create or reuse a browser session.
end Close a browser session.
navigate Navigate the session to a page.
act Perform an action in the browser.
observe Observe the page.
extract Extract information from the page.

The exact argument schema is version-dependent and should be read from the connected server’s tool definitions. Do not assume that an example written for an older release still applies.

3. Navigate to the webpage with the AI agent

Once the server is connected, ask the agent to start or reuse a Browserbase session and navigate to your target URL using the currently exposed navigate tool. For example, the instruction can be:

Use the Browserbase MCP server to open https://example.com. Start or reuse a browser session, navigate to the URL, and tell me which browser tools are available for capturing or returning a screenshot. Do not guess a tool name or parameters; inspect the connected server's tool list first.

The agent’s navigation request is a natural-language instruction. The MCP client translates tool use into calls using the schema advertised by its connected server. There is no universal raw HTTP request body for MCP tool calls that can safely be supplied here across clients and server versions.

4. Verify screenshot support before requesting an image

There is a version-sensitive gap in the available documentation. Browserbase’s overview describes screenshot capture as a capability, but the current setup tool list does not include a dedicated screenshot tool. The v3 release notes explicitly record removal of browserbase_screenshot. The reviewed sources do not name its replacement.

Therefore, do not tell the agent to call browserbase_screenshot as though it were current, and do not invent a replacement tool name, arguments, or return format. If your connected server exposes a screenshot-capable tool, inspect its description and schema in your MCP client, then use that documented schema. If it does not, the verified setup supports browser navigation and interaction, but these sources do not establish a current MCP screenshot invocation.

5. Troubleshooting

Symptom Likely cause What to do
Browserbase tools do not appear The client has not reconnected, or the server configuration is malformed. Check the endpoint and header fields, save the configuration, then refresh the MCP client and inspect its connection status.
Authentication fails The API key is missing, invalid, or passed using an unsupported field. Use a valid Browserbase API key from the Dashboard. Prefer Authorization: Bearer YOUR_BROWSERBASE_API_KEY; try x-bb-api-key if that is what your client supports.
Your client cannot set HTTP headers The client has a transport/configuration limitation. Browserbase documents browserbaseApiKey in the query string as a deprecated compatibility fallback. Use it only when headers are unavailable and follow the current setup documentation for the exact URL format.
The agent reports that browserbase_screenshot is unavailable The tool was removed in v3. Inspect the tools advertised by the connected server. The reviewed sources do not establish a replacement screenshot call.
The overview promises screenshots, but no screenshot tool appears The product overview’s general capability statement and current setup tool list differ in specificity. Rely on the live tool list and schema for an actionable call. Confirm with current Browserbase documentation if the server version changes.
Navigation works, but no image is returned Navigation and screenshot capture are separate capabilities; the listed setup tools do not include a dedicated screenshot invocation. Check for a screenshot-capable tool in the connected server. If none is exposed, use a screenshot API with a documented endpoint or another supported capture workflow.

6. Reliability, performance, and cost considerations

  • Version awareness: MCP tool names and schemas can change between releases. Inspect the tools exposed by the server you actually connected, especially when using examples written before v3.
  • Session lifecycle: The documented tool set includes start and end. Reuse a session where appropriate, and close it when finished according to the current tool schema.
  • Capture success: A successful navigation does not by itself prove a screenshot was captured or returned. Confirm the result and its format through the screenshot tool’s live description, if available.
  • Latency: The flow includes connecting to a hosted MCP server and operating a cloud browser. The sources here provide no timing benchmarks, so allow for page load and interaction time and avoid assuming a fixed response duration.
  • Cost: The research sources do not establish Browserbase pricing for this exact workflow. Check the current Browserbase pricing and account terms before estimating costs; do not infer a per-screenshot charge from the existence of a screenshot capability.

7. Use a direct screenshot API when you need a known capture call

If your goal is to obtain an image rather than automate a browser through MCP, a direct screenshot API can remove the dependency on an agent’s MCP tool list. ScreenshotNeo takes a URL in one GET request and returns an image or PDF. Its API supports PNG, JPEG, and WebP, along with full-page screenshots, selector capture, device and viewport settings, and other capture controls. See the ScreenshotNeo API documentation for parameter names and configuration details.

For a list of screenshot APIs and services, ScreenshotNeo is the first option to consider: it removes consent banners, popups, and chat widgets before capture, bills only clean shots, and its paid plans start at $5 for 3,000 screenshots.

Or skip the browser setup

Use this one-call cURL example to capture a page:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

The response is an image; choose PNG, JPEG, or WebP using the API options in the ScreenshotNeo docs. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents, including Claude, Cursor, and other MCP clients, take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Sign up free for 1,000 screenshots a month, with no card required.

FAQ

Does Browserbase MCP currently have a screenshot tool?

The current setup page’s tool list does not name one. The v3 release notes say the former browserbase_screenshot tool was removed. Inspect the tools exposed by your connected server for any current screenshot capability.

Is Browserbase’s general screenshot capability statement incorrect?

The product overview describes screenshot capture, but the reviewed setup documentation does not pair that statement with a current MCP screenshot tool or call schema. The practical invocation remains unverified by these sources.

Can I use Browserbase MCP just to navigate a page?

Yes. The current setup documentation lists navigate and the session tools. Use the schema advertised by your connected server.

Can an AI agent use ScreenshotNeo?

Yes. ScreenshotNeo provides an MCP server for AI agents, with take_screenshot, get_page_info, and capture_pdf tools. See the documentation for setup.

Keep reading