Hyperbrowser MCP: What It Is and How to Run It

# Hyperbrowser MCP: What It Is and How to Run It

Hyperbrowser MCP is a Model Context Protocol server that exposes Hyperbrowser's cloud browser sessions as tools an AI agent can call. Instead of writing Playwright glue code, you point an MCP-capable client — Claude Desktop, Cursor, or a custom agent loop — at the server, and the model gets tools to create a browser session, navigate, click, type, and extract content. This post explains what that server actually does, where MCP stops being enough, and how to move the same workload onto a hosted Chromium runtime you control. If you are evaluating browser runtimes for agents more broadly, start with remote browsers for AI agents and come back here for the MCP specifics.

What Hyperbrowser MCP actually is

MCP is an open protocol for connecting language models to external tools and data. A server advertises a list of tools with JSON schemas; the client (the model host) decides when to call them. Hyperbrowser's MCP server wraps its browser API in that shape, so a model can request "open this URL and return the visible text" without the developer hand-writing a tool definition.

The practical consequences:

• Tool-call granularity is fixed by the server. You get the operations Hyperbrowser chose to expose. If your agent needs a CDP command, a specific header override, or a custom wait condition, you are constrained by the tool surface.
• The model, not your code, sequences actions. That is the point of MCP, but it also means retries, timeouts, and error recovery live in the prompt loop rather than in deterministic code.
• Session lifecycle is managed for you. The server creates and tears down sessions. You generally do not get a raw WebSocket endpoint to attach Playwright to.

That last point is the fork in the road. MCP is excellent for exploratory, low-volume agent work. It is a poor fit when you need the same session driven by both a model and your own test harness, or when you need to replay a run deterministically.

MCP versus direct CDP access

The core trade-off is abstraction versus control. MCP hides the browser; CDP exposes it. Here is how the two approaches compare for production agent work.

If your agent only ever needs "go here, read this," MCP is fine. The moment you need to assert on DOM state, intercept network requests, or run the same script across 50 sessions in CI, you want CDP. The Chrome DevTools Protocol documentation is the reference for what that surface includes.

Where MCP servers break down in production

Three failure modes show up repeatedly when teams move MCP browser agents past the demo stage.

1. The model burns turns on mechanics. Every click is a tool call and a round trip. A ten-step form fill becomes ten model invocations, each with latency and token cost. Deterministic code does the same work in one function.

2. Error handling is probabilistic. When a selector changes, the model may retry, may hallucinate a different element, or may give up. There is no exception to catch. Production agents need typed errors and bounded retries.

3. Observability is thin. You see tool calls, not the browser's internal state. When a run fails, you cannot easily inspect the network log, console output, or DOM snapshot at the failure point unless the provider surfaces it.

None of this makes MCP wrong. It makes it a front-end for a runtime. The runtime underneath still has to be a real browser with real isolation, real profiles, and real debugging. That is the layer Remote Browser provides, and it is why the hosted runtime model matters regardless of whether your agent speaks MCP or CDP.

Running the same workload on hosted Chromium

The migration path from an MCP-driven agent to a code-driven one is straightforward: replace tool calls with CDP commands against a session you create yourself. Remote Browser gives you a session endpoint, a live viewer, persistent profiles, and configurable browser settings, and you connect with the library you already use.

The example below uses Playwright's connectOverCDP. It creates a session through the API, attaches, and runs a deterministic task. Replace the endpoint and token with values from your account; see /documentation for the current session API shape.

import { chromium, type Browser, type Page } from "playwright";

interface SessionResponse {
  id: string;
  cdpUrl: string;
}

async function createSession(): Promise<SessionResponse> {
  const res = await fetch("https://api.remote-browser.dev/v1/sessions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.REMOTE_BROWSER_TOKEN}`,
    },
    body: JSON.stringify({
      // Persistent profile keeps cookies and logins across runs.
      profileId: "agent-checkout",
      // Configurable browser settings: locale, timezone, viewport.
      locale: "en-US",
      timezone: "America/New_York",
    }),
  });
  if (!res.ok) throw new Error(`session create failed: ${res.status}`);
  return (await res.json()) as SessionResponse;
}

async function runTask(): Promise<void> {
  const session = await createSession();
  let browser: Browser | undefined;

  try {
    browser = await chromium.connectOverCDP(session.cdpUrl);
    const context = browser.contexts()[0];
    const page: Page = context.pages()[0] ?? (await context.newPage());

    await page.goto("https://example.com/orders", {
      waitUntil: "domcontentloaded",
    });

    // Deterministic extraction — no model in the loop.
    const rows = await page.locator("table.orders tbody tr").evaluateAll(
      (trs) =>
        trs.map((tr) => ({
          id: tr.querySelector("td.id")?.textContent?.trim() ?? "",
          total: tr.querySelector("td.total")?.textContent?.trim() ?? "",
        })),
    );

    console.log(JSON.stringify(rows, null, 2));
  } finally {
    // Always release the session; billing is per browser-hour.
    await browser?.close();
  }
}

runTask().catch((err) => {
  console.error(err);
  process.exit(1);
});

Two details matter here. First, connectOverCDP gives you the full Playwright API on a remote browser — locators, auto-waiting, network interception — without installing Chromium locally. Second, the finally block is not optional. Sessions are metered, and orphaned sessions are the most common source of surprise cost. Check /pricing for how metering works today.

Choosing between MCP and a runtime

Use this as a decision checklist rather than a rule:

• Prototype or internal tool, one user, chat-driven? MCP is the fastest path. Accept the fixed tool surface.
• Agent runs unattended on a schedule? Use CDP with explicit retries and a session budget.
• Need to replay a failed run? CDP plus recordings. MCP tool logs rarely capture enough browser state.
• Multiple agents sharing a login? Persistent profiles on a hosted runtime, not per-call sessions.
• Evaluating providers? Compare on session start latency, stealth behavior, profile persistence, and price per browser-hour — not on tool count.

The MCP ecosystem is moving fast, and servers like Hyperbrowser's are a reasonable way to get an agent browsing in an afternoon. The question worth asking is what happens on day thirty, when the agent is in a cron job and someone has to debug why it clicked the wrong button. At that point you want a session ID, a CDP endpoint, and a viewer — which is exactly the remote control surface a hosted runtime gives you.

What to verify before committing

If you are comparing Hyperbrowser MCP against other options, test these on your own workload:

1. Session start time. Measure p50 and p95 from API call to first usable page.
2. Reconnect behavior. Kill your client mid-run and see whether the session survives.
3. Profile persistence. Log in once, run again, confirm the session is still authenticated.
4. Network egress. Confirm the proxy region you need is available and stable.
5. Cost model. Understand whether you pay per session, per browser-hour, or per tool call. See /pricing for Remote Browser's current terms.
6. Debug artifacts. Check whether you get console logs, network traces, and screenshots on failure.

Run the same script against each candidate. The differences show up in the tail, not the median.

Bottom line

Hyperbrowser MCP is a useful adapter: it turns a cloud browser into tools a model can call, which lowers the barrier to building a browsing agent. It is not a runtime. Production agents need deterministic control, persistent state, and debuggable sessions, and those come from CDP access to a hosted Chromium instance. You can start with MCP and migrate later — the workload is the same, only the control surface changes. When you are ready to own that surface, run a remote browser online and connect with the library you already know.