Skip to main content

MCP setup

Connect an agent client (for example Cursor) to a live Stairway browser session over MCP. You and the agent share the same remote browser.

Prerequisites​

  1. A Stairway account and a browser session that is running (or that you can resume).
  2. An MCP client that supports either:
    • Direct Streamable HTTP (url + Authorization header) — preferred for Cursor, or
    • stdio only — use the Supergateway bridge described below.

1. Open Configure MCP​

On the Dashboard (or the session detail page), open the session menu and choose Configure MCP.

2. Mint a token​

In the dialog, set how long the token should last (from 1 hour up to 7 days; default 24 hours), then mint / refresh the token.

You get:

  • MCP URL for that session
  • Bearer token — a short-lived token for that session
  • Ready-to-paste client JSON for your MCP settings

Treat the token like a password. Anyone with the URL and token can drive that session until it expires.

Prefer this when your client supports a remote MCP server with custom headers (Cursor does).

Example shape (server name uses the first eight characters of the session id):

{
  "mcpServers": {
    "stairway-browser-xxxxxxxx": {
      "url": "https://your-host/m/<session-id>/mcp/",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Copy the JSON from the dialog, paste it into your client’s MCP config, and reload MCP servers.

4. Supergateway (stdio clients)​

If the client only speaks stdio MCP, use the Supergateway option. It wraps the same Streamable HTTP endpoint:

{
  "mcpServers": {
    "stairway-browser-xxxxxxxx": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://your-host/m/<session-id>/mcp/",
        "--header",
        "authorization:Bearer <token>"
      ]
    }
  }
}

5. What agents typically do​

A solid loop looks like:

  1. Navigate to a URL
  2. Snapshot the page to find interactive elements
  3. Click / type / press keys using refs from the snapshot
  4. Optionally log in with authorized credentials, handle challenges when available, or capture HAR / screenshots
  5. Repeat until the task is done

You can still open the streamed browser yourself while the agent works — same session.

Capabilities​

Your MCP client lists the tools available for the session. Typical categories include:

CategoryWhat you can do
Navigation & groundingOpen URLs, inspect the page, take screenshots, wait for readiness
InteractionClick, type, press keys, scroll, dismiss overlays
AuthLog in (or register) with credentials authorized at session create
Captcha helpersAssist with challenges when available
HAR / networkStart and finish HAR capture for downloadable artifacts
SessionInspect session info, snapshot / restore, start / stop / restart

Use your client’s tool list as the source of truth for exact names.

Tips​

  • Mint a new token if the old one expired or was exposed.
  • Keep sessions you automate under a clear nickname so humans and agents pick the right one.
  • Files the agent (or you) download appear on Downloads.