Creates a session: one isolated machine with a browser, a shell or both, and a /workspace disk they share. With no inputs you get a browser and, when your plan allows it, a shell. Call it first: it returns the sessionId that every other session tool needs. All of its inputs are optional. Use them for a shell-only session, a browser-only session, a proxy, a different timeout, a saved browser profile to start from, or credentials in the shell.

Inputs

Name	Type	Default	Allowed values	Description
`browser`	`boolean`	true	–	Give the session a browser. Set it to false, with a shell, for a shell-only session: it has no live view, and the browser tools are refused. A session needs a browser, a shell or both.
`shell`	`boolean`	true	–	Add a bash shell next to the browser. Your plan must include shell sessions. When you leave it out and the plan or the API does not allow a shell, you get a browser-only session. With `browser` false the shell is the whole session, so that fallback is skipped and you see the real error.
`timeout`	`number`	your plan's longest session, at most 1800	–	How long the session may run, in seconds.
`proxyType`	`string`	–	`residential`, `datacenter`	Browse through the platform's residential (home) or datacenter IPs. Without it, no proxy.
`proxyCountry`	`string`	–	–	Two-letter country code for the proxy, for example DE.
`proxyCity`	`string`	–	–	Residential only, for example berlin. Needs proxyCountry.
`blockAds`	`boolean`	false	–	Refuse requests to ad and tracker sites: pages load faster, with less clutter.
`cookieBanners`	`string`	reject	`reject`, `off`	"reject" answers cookie consent banners with Reject all; "off" leaves them.
`profile`	`string`	–	–	The id of a saved browser profile to start from: its cookies and logins.
`persistProfile`	`boolean`	false	–	Save what the session signs in to back into the profile when it stops. Needs profile.
`credentials`	`array of strings`	–	–	Names of saved credentials to export into the shell, for those whose scope allows it (see credentials_list). Needs a shell. At most 50. With `MCP_TOOLS=directory` the server leaves this out.

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.

tools/call

{  "name": "session_create",  "arguments": {    "proxyType": "residential",    "proxyCountry": "DE"  }}

What it returns

The new session's id, its live view URL (stdio only, and null for a session without a browser), the workspace path and whether it has a shell, as JSON text.

Result

{  "sessionId": "6c1f3c9e-1d2a-4f67-9b0e-1b2c3d4e5f60",  "liveUrl": "https://…/live/6c1f3c9e-…?token=…",  "workspace": "/workspace",  "shell": true}

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.

Annotation	Value
`title`	Create a session
`readOnlyHint`	`false`
`destructiveHint`	`false`
`openWorldHint`	`false`

Good to know

The session runs, and is billed, until you stop it with session_stop or it reaches its timeout. Ask the model to stop it when the work is done.
For a shell-only session send {"browser": false, "shell": true}. Its liveUrl is null, and the browser_* tools answer browser_disabled. The shell, files and session_* tools work as on any session.
The proxy keeps one IP for the whole session, and only the browser uses it: shell commands connect directly.
US states, your own proxy and proxy rules by site are available through the API and SDKs, not this tool.
The live view URL lets anyone who has it control the browser. Share it only with people who should. Over HTTP (the hosted server, or your own with --http) the result has no liveUrl, for that reason.
A secret goes into the shell as $NAME, and a password as $NAME_USERNAME and $NAME_PASSWORD. Anything that runs in the shell can read them, so export only what a command needs.
To sign in on a page, do not export a credential: use browser_type with credential, which the model cannot read.

The same thing with the API

Endpoint	Reference
`POST /v1/sessions`	Create a session

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.