Connecting an MCP client to Guard.ch

Give an AI agent a real isolated Chrome browser through one hosted Model Context Protocol endpoint.

The Guard.ch teamProduct researchJul 23, 2026

Guard.ch runs a hosted Streamable HTTP MCP server. Claude Code, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI and other clients that support authentication headers connect to one URL and receive 21 browser tools.

There is no local browser service and no model API key to configure. Your client supplies the model; Guard.ch supplies the isolated browser, session lifecycle and optional human handoff.

What you need

Endpoint: https://api.guard.ch/mcp
Transport: Streamable HTTP
Authentication: A Guard.ch app key
Plan: Any active Guard.ch plan
Concurrency: One running browser session per plan seat

Endpoint and authentication

Connect the client to this single MCP endpoint:

https://api.guard.ch/mcp

Pass a Guard.ch app key in one of these headers. Keys in URLs are rejected so they cannot leak into browser history, proxy logs or analytics:

Authorization: Bearer YOUR_API_KEY as a Bearer token in the Authorization header (recommended)
x-api-key: YOUR_API_KEY in an x-api-key header

Connect your client

Choose the matching example and replace YOUR_API_KEY with an app key from your dashboard. A client that cannot send an authentication header is not supported by the app-key endpoint.

Claude Code

claude mcp add --transport http guardch https://api.guard.ch/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "guardch": {
      "url": "https://api.guard.ch/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

VS Code

code --add-mcp '{"name":"guardch","type":"http","url":"https://api.guard.ch/mcp","headers":{"Authorization":"Bearer YOUR_API_KEY"}}'

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "guardch": {
      "serverUrl": "https://api.guard.ch/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Codex CLI

codex mcp add guardch --url https://api.guard.ch/mcp \
  --bearer-token-env-var GUARDCH_API_KEY

Gemini CLI

gemini mcp add --transport http guardch https://api.guard.ch/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Available tools

The server exposes 21 tools with structured results and safety annotations. An agent can start with browser_navigate: Guard.ch creates a session automatically and returns a snapshot with ref ids for later interactions.

Session lifecycle

Tool	Description
`browser_create_session`	Start a retry-safe session with an optional timeout, screen size, exit country, proxy or initial URL.
`browser_list_sessions`	List active sessions with their ids and live-view URLs.
`browser_stop_session`	Stop a session and free its concurrency slot.
`browser_get_usage`	Show current concurrency and session totals for the last 30 days.

Page control

Tool	Description
`browser_navigate`	Open a URL and create a session automatically when needed.
`browser_navigate_back`	Return to the previous page.
`browser_snapshot`	Return an accessibility snapshot with ref ids.
`browser_click`	Click an element by snapshot ref.
`browser_type`	Type into an input and optionally submit with Enter.
`browser_press_key`	Press one key, such as Enter or Escape.
`browser_hover`	Hover an element by snapshot ref.
`browser_scroll`	Scroll by pixels or bring an element into view.
`browser_wait_for`	Wait for text, a URL, a load state or text to disappear.
`browser_handle_dialog`	Accept or dismiss the next browser dialog.
`browser_select_option`	Choose options in a select element.
`browser_screenshot`	Capture the viewport or full page as JPEG.
`browser_evaluate`	Run JavaScript in the page and return its result.
`browser_tab_new`	Open a new tab.
`browser_tab_select`	Switch to another tab.
`browser_tab_close`	Close a tab.
`browser_tab_list`	List tabs with stable ids, titles and URLs.

How sessions behave

Automatic creation. The first page-tool call creates a session when this app key has none active. If the key has several active sessions, Guard.ch requires session_id instead of choosing one unpredictably.
Automatic cleanup. A session ends two minutes after the last tool call or CDP disconnect, and always at its absolute timeout. Call browser_stop_session to finish sooner.
Human handoff. The live-view URL lets a person watch or take over with mouse and keyboard for steps such as a login or captcha.
Location control. Choose an exit country or city, or route the browser through your own proxy.
One session per seat. Each plan seat supplies one concurrent browser slot. Creation is denied instead of queued while that slot is occupied.

REST and CDP access

The same browser sessions are available without MCP. Create and manage them through the Guard.ch API, then connect Playwright or Puppeteer to the returned CDP websocket.

POST /v8/web/sessions creates a retry-safe session with an optional screen size and returns connectUrl plus liveViewUrl
GET /v8/web/sessions lists active sessions; use status=all for the 30-day history
DELETE /v8/web/sessions/:id stops a session
GET /v8/web/usage returns usage and concurrency

This example creates a session. Pass its connectUrl to Playwright as shown below.

curl -X POST https://api.guard.ch/v8/web/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout":900,"country":"us","screen":{"width":1440,"height":900},"idempotencyKey":"task-123"}'

const browser = await chromium.connectOverCDP(session.connectUrl);

Next steps

Create a key under Apps, add the endpoint to your client and ask it to open a page. For help with a client or a larger deployment, contact us.