Connecting an AI assistant over MCP

MCP (Model Context Protocol) gives your assistant additional tools. With Guard.ch, it can open and read pages in an isolated cloud browser, click, fill forms, upload files, run JavaScript and take screenshots. You choose the exit location.

You don't need a local browser service or driver. Guard.ch provides the browser, manages the session and gives you a live view you can take over at any time. The model stays with your client; there is no model key to configure here.

Connect in three steps

1. Create an app key

   Create an app key for your assistant in the Guard.ch dashboard.

   Create an app key

2. Add the server to your client

   Choose your client, add the configuration and replace YOUR_API_KEY with your app key. Set up each device the same way if you use more than one.

   Restart the client so it recognises the new server. The browser runs on Guard.ch; check your client guide for any additional setup.

3. Try the connection

   Give your assistant a task that needs a browser. It opens the session itself:

   Open example.com in a Guard.ch browser and tell me what the page says.

   If your assistant describes the page, the connection works. If it reports no tools, restart the client so it reloads the MCP configuration.

What you need

Endpoint

https://api.guard.ch/mcp

Transport

Streamable HTTP, stateless per request

Authentication

A Guard.ch app key in a request header

Plan

A plan with programmatic access; the 30-day trial includes it

Browsers

Any Chromium-family image your plan allows, Chrome by default

Concurrency

Up to three concurrent sessions per person, shared with their agents

Manage your app key

• One key per client. A separate key for each assistant, machine or pipeline lets you revoke access for one client without interrupting the others.
• Choose an expiry. At creation, choose no expiry, 30 days, 90 days or one year. An expiry date is useful for unattended processes.
• Copy it once. The key is shown a single time, at creation. A lost key is replaced, not recovered: revoke it and create another.
• Revocation is immediate. A revoked key stops working at once, including in the middle of a conversation.

Endpoint and authentication

The server speaks Model Context Protocol over Streamable HTTP. Each request stands on its own, so your client can restart without the server having to keep conversation state.

https://api.beta.browser.lol/mcp

Send the key in one of these two headers. It never belongs in the URL, where it would leak into browser history, proxy logs and analytics:

• Authorization: Bearer YOUR_API_KEY as a Bearer token, which is what every snippet below uses.
• x-api-key: YOUR_API_KEY for clients that cannot set Authorization.

Client configuration examples

claude mcp add --scope user --transport http guardch https://api.beta.browser.lol/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "guardch": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.beta.browser.lol/mcp",
        "--header", "Authorization:Bearer YOUR_API_KEY"
      ]
    }
  }
}

{
  "mcpServers": {
    "guardch": {
      "url": "https://api.beta.browser.lol/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

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

export GUARDCH_API_KEY="YOUR_API_KEY"
codex mcp add guardch --url https://api.beta.browser.lol/mcp \
  --bearer-token-env-var GUARDCH_API_KEY

gemini mcp add --scope user --transport http guardch https://api.beta.browser.lol/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "guardch": {
      "serverUrl": "https://api.beta.browser.lol/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Choosing a browser and an exit location

image selects an available Chromium browser when you create a session. Chrome is the default. Firefox and Tor cannot be driven programmatically; a request for either returns the supported browser IDs.

Use country to choose an exit country or city (us, de, us-dal). residential uses a residential address where available; proxy uses your own proxy. browser_set_location can change the location during a session.

Watching a session, and taking it over

Every session comes with a live view URL, and the sessions your agents are running are listed on the Agents tab of your dashboard. Open one in the same viewer you use for your own sessions: the page streams live, and you can end the session from there.

If the assistant needs help with a sign-in, captcha or decision, you can take over the mouse and keyboard. It can then continue in the same browser.

Live analysis beside the page

On a Chromium browser, Guard.ch's analysis lane can run beside the page: requests, redirect chains, response headers, console output, security issues, downloads, forms, cookies and storage, the technologies and trackers it recognises, WHOIS, IP and certificate look-ups on demand, and a verdict per host that shows its sources.

browser_session_analysis turns analysis on or off for a session started by a person in the app. When it is on, you can follow the findings live and the dashboard lists the session as an investigation. Sessions started by the assistant do not support this control; attempts to switch analysis on or off return analysis_unavailable.

How the sessions behave

• Sessions can start automatically. The first page tool opens a session when none is running for that key. If several sessions are running, Guard.ch refuses a call without a session_id instead of guessing which browser you mean.
• Sessions end automatically. You do not set a lifetime. A session ends a few minutes after the last tool call or CDP disconnect, and 18 hours after it started at the latest. Closing it yourself frees the slot immediately.
• Retries are safe. An idempotency key returns the successful creation response on a retry instead of opening a second browser. This helps with queues and retried jobs.
• People and agents share one account. Your assistant can list, drive and close the sessions you started in the app, and you can do the same with its own. Closing one of yours closes the window you are watching, which is a good reason to name sessions.
• Access stays within your account. Every tool works on your own sessions only. No other member's sessions are visible or reachable through the server.

Limits and refusals

• Programmatic access is a plan feature. Without it every call answers with an upgrade notice instead of a tool result. Both paid plans include it, and so does the 30-day trial.
• Up to three concurrent sessions per person. Agent sessions share this limit with your own sessions. Once all three slots are in use, new sessions are rejected rather than queued.
• No per-tool charge. Your plan must include programmatic access. Individual tool calls carry no additional fee. Residential egress counts against your workspace data allowance.
• Creation is rate-limited. Per-minute, hourly and daily limits protect the platform from excessive session creation. Check the response status and delay further attempts if you reach a limit.
• Nothing is stored. A closed session is gone with everything it saw. The session list keeps 30 days of entries (what ran, when and for how long), never the pages themselves.

The tools your assistant gets

The server provides 33 browser_ tools with structured results. An assistant can start with browser_navigate: Guard.ch opens a session if needed and returns an accessibility snapshot with references for later actions. For many tasks, this is more precise and efficient than a screenshot.

Security

• An app key is a credential: keep it in your client's secret store or an environment variable, never in a shared config file or a link. If it is exposed, revoke it on the Apps tab.
• The key travels in a request header. Keep it out of URLs, where it would land in browser history, proxy logs and analytics.
• Pages load in our infrastructure, never on the machine running the assistant and never in a browser profile of yours: every session is a throwaway container.
• The MCP server uses no model of its own. It returns the requested results to your client, where you decide which model processes them.
• An agent's session is as visible as a person's. It is listed in the dashboard, watchable live, and can be ended by hand at any moment.
• Everything runs over TLS, and the sessions are covered by the same DPA as the rest of the product.

Troubleshooting

If something goes wrong, check these common causes first:

The client lists no tools. It has not reloaded its configuration. Restart it after adding the server, and check the URL is the /mcp endpoint above rather than the REST base.

Every call answers with an upgrade notice. The account behind the key has no plan with programmatic access. Start the trial, or ask a workspace manager for a seat.

A call is refused as an ambiguous session. Two or more sessions are running on that key, so Guard.ch will not guess which one you mean. List them and pass the session_id explicitly from then on.

Creating a session is refused. Either all three of the account's running sessions are in use, or the image asked for cannot be driven programmatically. The refusal says which, and names the ids you may use.

The key stopped working mid-conversation. It was revoked or reached its expiry date. Create a new one and update the client's configuration.

The same browsers without MCP

A client that does not speak MCP can create the same sessions over REST and attach Playwright or Puppeteer to the CDP endpoint each one returns. The API integration guide covers that path.

Next steps

Create a key under Apps, add the endpoint to your client and ask the assistant to open a page. You can watch or end its sessions on the Agents tab. If your client is missing from this guide, get in touch.