Skip to main content

MCP setup

Connect an MCP client (e.g. Claude Code, OpenAI Codex) to Stairway over MCP. One MCP server covers your whole account: agents list or create browsers, then drive them with a session_id.

Prerequisites​

  1. A Stairway account.
  2. An API token — create one under Account → API & MCP (Tokens tab), or Settings → API credentials.
  3. An MCP client that supports either:
    • Direct Streamable HTTP (url + Authorization header) — preferred when your client supports it, or
    • stdio only — use the Supergateway bridge described below.

1. Create an API token​

Open Account → API & MCP, stay on the Tokens tab, create a named token (optional expiration), and copy the secret once. The web UI also stores that secret in this browser so the MCP tab can reuse it.

Treat the token like a password. It authenticates as you for consumer REST and MCP. It cannot call system-admin APIs.

After you create a token, Stairway switches you to the MCP tab so you can copy client config immediately.

2. Copy MCP config​

On the same API & MCP page, open the MCP tab:

  • Pick an active token from the dropdown (or paste the secret if it was created in another browser).
  • Copy the generated client JSON (Direct Streamable HTTP or Supergateway).

The config always points at the universal endpoint (/api/mcp/), not a per-browser URL. Agents pass a session_id into browser tools when they need a specific session.

Alternate shortcuts​

You can also open Configure MCP from a session row on the Dashboard, session detail page, or the noVNC toolbar. Those dialogs mint a drive token for that browser only — not your account API token. Settings → Configure MCP deep-links to the account MCP tab (account token, for orchestrators).

{
  "mcpServers": {
    "stairway": {
      "url": "https://your-host/api/mcp/",
      "headers": {
        "Authorization": "Bearer stw_<prefix>_<secret>"
      }
    }
  }
}

Paste into your client’s MCP settings and reload MCP servers.

4. Supergateway (stdio clients)​

{
  "mcpServers": {
    "stairway": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://your-host/api/mcp/",
        "--header",
        "authorization:Bearer stw_<prefix>_<secret>"
      ]
    }
  }
}

5. What agents typically do​

  1. browsers_list / browsers_recommend — prefer a matching running session
  2. browsers_create — only if needed; pass country / city and leave UA/locale unset so stealth matching applies. Optional idle_timeout_secs for known-slow tasks.
  3. Pass session_id into every browser_* tool
  4. Navigate → snapshot → click/type → optional login / captcha / HAR
  5. During long human-in-the-loop waits, call browsers_keepalive (interaction tools already refresh the idle clock)
  6. Stop, browsers_delete (for stuck pending/error sessions), or leave the session running as needed

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

If agent tools fail​

Stay on Stairway MCP: browsers_info → browsers_start / browsers_restart → wait until ready → retry. Agents must not fall back to a local IDE browser harness (e.g. Cursor’s built-in browser) to drive noVNC as a substitute. If recovery fails, report the error and stop.

Regional stealth​

When creating a browser for a region, pass the egress country (and optional city). With match_stealth=true (default), Stairway picks locale and User-Agent to match that exit so the browser looks like a local visitor.

Capabilities​

CategoryTools
Accountaccount_info, account_usage
Browsersbrowsers_list, browsers_recommend, browsers_create, browsers_info, browsers_start / stop / delete / restart / keepalive
Navigation & groundingbrowser_navigate, snapshot, screenshot, wait, … (all require session_id)
Interactionclick, type, keys, scroll, overlays
Auth / captcha / HARsame as before, with session_id

Consumer REST​

The same API token works as Authorization: Bearer stw_… on user /api/* routes (browsers, analytics, credentials you own, etc.). Admin routes require a normal login session.