browser_login

Signs the session's browser in with a saved password credential. A short run inside the session types the credential on its own sites only, so the model never sees the password, a 2FA code or a sign-in link. Give url to start from the site's sign-in page.

Inputs

This tool works in a session with a browser. On a shell-only session (created with browser: false) it answers browser_disabled. See the three kinds of session.

sessionId is the id that session_create returned. The server keeps no default session. If that session is stopped, this tool resumes it first, as it was (a resume starts a machine again, and billing with it).

Example call

This is what an MCP client sends. You do not write it yourself: ask the model in plain words and it calls the tool.

{  "name": "browser_login",  "arguments": {    "sessionId": "6c1f3c9e-1d2a-4f67-9b0e-1b2c3d4e5f60",    "credential": "SHOP",    "url": "https://shop.example.com/login"  }}

What it returns

The page the browser is on after signing in: its title and address, without the query. Or the error.

Signed in with SHOP: Your account (https://shop.example.com/account).

When a call fails, the result is marked as an error. Its text starts with the API’s error code, such as unauthorized or session_not_running, followed by its message.

Annotations

The server tells every client what this tool does to the world, so a client can decide what to ask you about before it runs.

Good to know

• A short run in the session does the work: at most 15 steps, browser tools only, only that credential and only pages on its sites. It uses the project's default model and counts as an agent run (30 a minute per project). Needs a session with a browser and a plan with password credentials (the loginDetails feature).
• A password whose codeSource is push or url makes the call wait, up to the credential's code timeout (5 minutes by default), for the 2FA code or sign-in link your own system sends. Tell the person that a code is needed. They send it with the CLI (boxline credentials push-code SHOP) or an SDK (credentials.pushCode), never through the chat.
• The call is stopped after 15 steps of 30 seconds plus the credential's code timeout, and answers credential_login_timeout. A code that never arrives gives credential_code_timeout, a sign-in link for another site credential_link_wrong_site, and any other failure credential_login_failed with the id of the run.
• When the page is the one a sign-in link opened, only its origin is shown: such a link can keep its token in the path. Nothing the run learned (a code, a link, a value) is ever in the answer.
• Not available when the server runs with MCP_TOOLS=directory.

The same thing with the API