Start an autonomous browser agent on a plain-English task, e.g. 'find the pricing page on example.com and return the cheapest plan'. Returns a runid immediately — poll getagentrun for the result. Pass resultschema for structured output, or agentid to reuse a saved agent. Metered per run; 402 means the allowance is exhausted. A static page read uses no browser, so sessionid may be null.
Get an agent run by ID — status (RUNNING, COMPLETED, FAILED, STOPPED), its result summary and steps taken, and the failure cause if it did not complete. Poll after runagent; reading is free and consumes no agent call. sessionid is often null even when COMPLETED — a static page read uses no browser, so a missing session is not a failure.
List agent runs, newest first, with cursor pagination. Filter server-side by status, agentid, or a startat/endat time window. Pass nextcursor from a previous response as cursor for the next page.
Get the step-by-step message stream for an agent run — what the agent saw, decided, and did. Use to debug a run that failed or returned an unexpected result. Pass next_since from a previous response as since to poll only newer messages.
Stop a RUNNING agent run before it finishes, ending its browser session. Use to cut off a run that is looping or heading somewhere unintended. A run that already finished returns 409 'Run has already ended' — that is terminal, so re-read it with getagentrun instead of retrying.
Create a reusable agent: a name plus a standing system prompt and result schema that every run started with its agent_id inherits. Use when the same browsing job runs repeatedly and should return the same shape each time.
Get a reusable agent by ID, including its system prompt and result schema.
List reusable agents with cursor pagination. Call this to find an agentid to pass to runagent. Filter server-side by a startat/endat creation-time window. Pass next_cursor from a previous response as cursor for the next page.
Update a reusable agent's name, system prompt, or result schema. Only the fields provided change; omitted fields keep their current values.
Delete a reusable agent permanently. Runs already started with it are unaffected, but its agentid can no longer be passed to runagent.
Create a context that persists cookies and local storage across browser sessions. Pass the returned id to createsession as browsersettings={'context': {'id': <id>, 'persist': true}} so a later session resumes an existing login instead of signing in again.
Get a browser context by ID, including which project owns it and when it was created.
Delete a browser context permanently, discarding the cookies and local storage it held. Sessions already using it are unaffected; future sessions cannot resume it.
Fetch a URL and return its content, status code, and headers without starting a browser session. Use format='markdown' for LLM-friendly text, or format='json' with a schema to extract structured fields. Prefer this over create_session for reading a page. Errors: 402 means the monthly fetch allowance is exhausted.
List the Browserbase projects this API key can reach, with each project's concurrency limit and default session timeout. Call this first to get a project_id for session and context tools.
Get one Browserbase project by ID, including its concurrency limit and default session timeout. Call list_projects to discover project IDs.
Get browser minutes and proxy bytes consumed by a project this billing period. Use before starting sessions or agent runs to check remaining allowance. Both figures round DOWN, so 0 browser minutes means 'under a minute billed', NOT 'no sessions ran' — call list_sessions to see whether any actually ran.
Search the web and return structured results with titles and URLs. Pass a result URL to fetch_page to read the page itself. Errors: 402 means the monthly search allowance is exhausted.
Start a cloud browser session and return its CDP connecturl for an external automation to drive. Sessions consume browser minutes until they end, so call releasesession when done. Errors: 429 means the project's concurrency limit or session-per-minute limit was hit; 403 means a requested feature (proxies, Verified) needs a paid plan.
List browser sessions, optionally filtered by status (PENDING, RUNNING, COMPLETED, ERROR, TIMEDOUT) or by user metadata via q. Both filters are applied server-side. Use status='RUNNING' to find sessions still consuming browser minutes. The q syntax is usermetadata['key']:'value' — a bare key:value is rejected with HTTP 400. Returns the newest limit sessions (default 100); total_available shows the rest.
Get one browser session by ID — status, region, timestamps, and proxy bytes used. Call listsessions or createsession to obtain a session ID.
Get the Chrome DevTools Protocol log for a session: the commands and events the browser recorded. Use to debug what an automation or agent run actually did. Returns the newest limit entries (default 100) without their CDP payloads; set include_payloads=true for the full bodies. Logs are retained for a limited window (7 days on the Free plan).
Get live view and debugger URLs for a RUNNING session, so a person can watch or take over the browser — the way to clear a login or CAPTCHA an automation cannot. Errors: 410 means the session already stopped and no live URL can exist; start a new session instead of retrying.
Release a RUNNING browser session so it stops consuming browser minutes and frees a concurrency slot. Use after an automation finishes, or to stop a session left running by keep_alive. Already-stopped sessions cannot be released.
Validate the Browserbase API key with a lightweight call to /v1/projects. Returns success plus a short message.
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
