Connecting an AI assistant over MCP

MCP (Model Context Protocol) gives your assistant additional tools. With Guard.ch, it operates an isolated cloud browser like a person: real mouse and keyboard input with human timing, so the site sees a visitor, not automation. It can open and read pages, click, fill forms, upload files 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.

What you need

Endpoint

https://api.guard.ch/mcp

Transport

Streamable HTTP, stateless per request

Authentication

Sign-in with your Guard.ch account (OAuth), or an 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

Connected apps and app keys

• Sign-in is the default. Almost every client signs in by itself through OAuth. Only the Guard.ch page asks for your account; the client never sees your password. The few that cannot sign in, and your own code, use an app key instead.
• Check before you allow. The page names the app, who published it and where it returns to. An app that registered itself is marked as unverified; allow it only if you just started connecting it.
• Disconnect at any time. Connected apps are listed on the Agents tab. Disconnecting one revokes all of its access at once, also in the middle of a conversation.
• App keys for automation. Scripts, pipelines and clients that cannot sign in use an app key from the Apps tab. Create a separate key per client so you can revoke one without interrupting the others.
• Keys expire and are shown once. A key expires after one year without use, or on a fixed date of your choice. It is shown only at creation; a lost key is revoked and replaced, not recovered.

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.guard.ch/mcp

Clients that support MCP authorization connect with the URL alone: the server answers the first request with a sign-in challenge, and the client opens the Guard.ch sign-in page. For automation, send an app key in one of these headers instead. A key never belongs in the URL, and the server does not accept it there:

• Authorization: Bearer YOUR_API_KEY as a Bearer token.
• x-api-key: YOUR_API_KEY for clients that cannot set Authorization.

Client configuration examples

{
  "mcpServers": {
    "guardch": {
      "url": "https://api.guard.ch/mcp"
    }
  }
}

claude mcp add --scope user --transport http guardch https://api.guard.ch/mcp

codex mcp add guardch --url https://api.guard.ch/mcp
codex mcp login guardch

gemini mcp add --scope user --transport http guardch https://api.guard.ch/mcp

copilot mcp add --transport http guardch https://api.guard.ch/mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "guardch": {
      "type": "remote",
      "url": "https://api.guard.ch/mcp"
    }
  }
}

extensions:
  guardch:
    name: guardch
    type: streamable_http
    uri: https://api.guard.ch/mcp
    enabled: true
    timeout: 300

amp mcp add guardch https://api.guard.ch/mcp

qwen mcp add --scope user --transport http guardch https://api.guard.ch/mcp

droid mcp add guardch https://api.guard.ch/mcp --type http

{
  "mcp": {
    "guardch": {
      "type": "http",
      "url": "https://api.guard.ch/mcp",
      "oauth": true
    }
  }
}

{
  "mcpServers": {
    "guardch": {
      "url": "https://api.guard.ch/mcp"
    }
  }
}

{
  "guardch": {
    "url": "https://api.guard.ch/mcp"
  }
}

{
  "mcpServers": {
    "guardch": {
      "url": "https://api.guard.ch/mcp"
    }
  }
}

{
  "servers": {
    "guardch": {
      "type": "http",
      "url": "https://api.guard.ch/mcp"
    }
  }
}

devin mcp add --scope user guardch https://api.guard.ch/mcp
devin mcp login guardch

{
  "context_servers": {
    "guardch": {
      "url": "https://api.guard.ch/mcp"
    }
  }
}

{
  "servers": {
    "guardch": {
      "url": "https://api.guard.ch/mcp"
    }
  }
}

{
  "mcpServers": {
    "guardch": {
      "type": "streamableHttp",
      "url": "https://api.guard.ch/mcp"
    }
  }
}

{
  "mcp": {
    "guardch": {
      "type": "remote",
      "url": "https://api.guard.ch/mcp"
    }
  }
}

name: guardch
version: 1.0.0
schema: v1
mcpServers:
  - name: guardch
    type: streamable-http
    url: https://api.guard.ch/mcp
    requestOptions:
      headers:
        Authorization: "Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "guardch": {
      "url": "https://api.guard.ch/mcp",
      "oauthScopes": [
        "mcp"
      ]
    }
  }
}

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

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

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

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "guardch",
      "server_url": "https://api.guard.ch/mcp",
      "authorization": "YOUR_API_KEY",
      "require_approval": "never"
    }
  ]
}

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://api.guard.ch/mcp",
      "name": "guardch",
      "authorization_token": "YOUR_API_KEY"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "guardch"
    }
  ]
}

from agents.mcp import MCPServerStreamableHttp

guardch = MCPServerStreamableHttp(
    name="guardch",
    params={"url": "https://api.guard.ch/mcp", "headers": {"Authorization": "Bearer YOUR_API_KEY"}},
)

import { createMCPClient } from "@ai-sdk/mcp";

const guardch = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.guard.ch/mcp",
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  },
});

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "guardch": {
        "transport": "http",
        "url": "https://api.guard.ch/mcp",
        "headers": {"Authorization": "Bearer YOUR_API_KEY"},
    }
})

{
  "mcpServers": {
    "guardch": {
      "type": "http",
      "url": "https://api.guard.ch/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. screen, language and keyboard_layout set the screen size, browser language and keyboard layout when the session starts.

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_session_update 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.

Control is automatic: the assistant's actions drive the browser. To step in, take over with the button in the live view. The assistant then stops and tells you: its actions report user_in_control, and reading still works. When you're done, hand control back and ask it to continue in the same browser. For a sign-in or captcha, it asks you with browser_ask_user.

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_update with analysis: true or analysis: false turns analysis on or off for a session on your account, whether you started it in the app or the assistant started it. You can also switch it in the live view. When it is on, you can follow the findings live and the dashboard lists the session as an investigation. A session on a browser without analysis support returns analysis_unavailable.

How the sessions behave

• Sessions can start automatically. The first page tool opens a session when none is running for that connection. 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 28 browser_ tools that operate the browser like a person: every click, keystroke and scroll is real mouse and keyboard input with human timing, so sites see a visitor, not automation. An assistant can start with browser_navigate: Guard.ch opens a session if needed and returns an accessibility snapshot with references for later actions, and browser_screenshot's pixels are the x/y coordinates browser_click, browser_hover, browser_drag and browser_scroll take.

Security

• Allow only apps you connected yourself. A connected app acts for your account until you disconnect it on the Agents tab.
• 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. Send it only in a header; the server refuses keys in a URL. If one is exposed, revoke it on the Apps tab.
• 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 signed-in account 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 connection, 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.

Access stopped working mid-conversation. The app was disconnected, or its app key was revoked, reached its expiry date or went unused for a year. Sign in again from the client, or create a new key.

The sign-in page cannot continue. A sign-in request expires after a few minutes and can be answered only once. Start connecting again from your client.

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.