Skip to main content
Glama

session_create

Create a persistent interactive browser session for multi-step interaction - clicking, typing, scrolling, reading state across page transitions. Use when the agent must INTERACT with a page (login flows, forms, pagination, click-through) rather than read it once. Returns session_id; persists 8 min idle. With persistent:true the login state survives idle eviction and server restarts - the same session_id revives logged-in.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNoInitial URL to navigate to (optional). `start_url` is honored as an alias (#115) — callers guessing that name must not land on about:blank.
widthNoInitial viewport width in CSS pixels. Pinned for the session's life (survives navigation) so element rects and media queries anchor to the same layout across every page of the visit.
heightNoInitial viewport height in CSS pixels.
mobileNoMobile device emulation (coarse pointer, no hover) for the initial viewport.
accountNoRun as a named login identity (the multi-account layer): a private cookie jar seeded from the account record, write-back to the account store after every action. Concurrent logins (`taobao-scraper` vs `taobao-publisher`) never clobber each other. The account record survives the session — a later create with the same name picks up the warm jar, plus the record's captured localStorage/sessionStorage (replayed onto the captured origin; an explicit `storage` param wins). 1-64 chars of [a-zA-Z0-9_-].
cookiesNoCookies to inject before navigation: `"name=value"` strings or CDP-style objects `{"name","value","domain",...}`. Lets the session start already logged-in. Round-trips with session_cookies.
storageNoWeb Storage to inject after the initial navigation lands: {"local_storage": {"k":"v"}, "session_storage": {"k":"v"}}. For login states that live in localStorage rather than the cookie jar. An optional "origin": "https://site" key holds the injection until a navigation lands on that origin (a session created without a start_url sits on about:blank first). Round-trips with session_storage.
ttl_secsNoIdle time-to-live in seconds before the session is evicted (default: 480, clamped 60..3600). Raise it for long workflows.
keepaliveNoExempt the session from the idle reaper: it lives until session_close or server exit, so a workflow interrupted by long non-browser steps keeps its login state.
use_proxyNoRoute through proxy (default: false)
persistentNoPersist the login state (cookies + localStorage/sessionStorage + viewport + dialog policy) to the server's local store after every action. If the session idles out — or the whole server restarts — the next call with the same session_id revives it logged-in (storageState-style recovery, no re-login). Explicit session_close drops the snapshot.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / account / description
      Previous value: -"Run as a named login identity (the multi-account layer): a private\ncookie jar seeded from the account record, write-back to the account\nstore after every action. Concurrent logins (`taobao-scraper` vs\n`taobao-publisher`) never clobber each other. The account record\nsurvives the session — a later create with the same name picks up\nthe warm jar. 1-64 chars of [a-zA-Z0-9_-]."New value: +"Run as a named login identity (the multi-account layer): a private\ncookie jar seeded from the account record, write-back to the account\nstore after every action. Concurrent logins (`taobao-scraper` vs\n`taobao-publisher`) never clobber each other. The account record\nsurvives the session — a later create with the same name picks up\nthe warm jar, plus the record's captured localStorage/sessionStorage\n(replayed onto the captured origin; an explicit `storage` param\nwins). 1-64 chars of [a-zA-Z0-9_-]."
    • changedInput schema / properties / storage / description
      Previous value: -"Web Storage to inject after the initial navigation lands:\n{\"local_storage\": {\"k\":\"v\"}, \"session_storage\": {\"k\":\"v\"}}. For login\nstates that live in localStorage rather than the cookie jar.\nRound-trips with session_storage."New value: +"Web Storage to inject after the initial navigation lands:\n{\"local_storage\": {\"k\":\"v\"}, \"session_storage\": {\"k\":\"v\"}}. For login\nstates that live in localStorage rather than the cookie jar. An\noptional \"origin\": \"https://site\" key holds the injection until a\nnavigation lands on that origin (a session created without a\nstart_url sits on about:blank first). Round-trips with\nsession_storage."
  2. Changed1 schema field changed
    • changedInput schema / properties / url / description
      Previous value: -"Initial URL to navigate to (optional)"New value: +"Initial URL to navigate to (optional). `start_url` is honored as an\nalias (#115) — callers guessing that name must not land on about:blank."
  3. Changed1 schema field changed
    • removedInput schema / title
      Removed value: -"SessionCreateParams"
  4. Changed1 schema field changed
    • addedInput schema / properties / account
      Added value: +{
      +  "default": null,
      +  "description": "Run as a named login identity (the multi-account layer): a private\ncookie jar seeded from the account record, write-back to the account\nstore after every action. Concurrent logins (`taobao-scraper` vs\n`taobao-publisher`) never clobber each other. The account record\nsurvives the session — a later create with the same name picks up\nthe warm jar. 1-64 chars of [a-zA-Z0-9_-].",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  5. Changed6 schema fields changed
    • changedInput schema / properties / cookies / description
      Previous value: -"Cookies to inject before navigation ([\"name=value\", ...]). Lets the\nsession start already logged-in. Round-trips with session_cookies."New value: +"Cookies to inject before navigation: `\"name=value\"` strings or\nCDP-style objects `{\"name\",\"value\",\"domain\",...}`. Lets the session\nstart already logged-in. Round-trips with session_cookies."
    • addedInput schema / properties / height
      Added value: +{
      +  "description": "Initial viewport height in CSS pixels.",
      +  "format": "uint32",
      +  "minimum": 0,
      +  "type": [
      +    "integer",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / keepalive
      Added value: +{
      +  "default": false,
      +  "description": "Exempt the session from the idle reaper: it lives until\nsession_close or server exit, so a workflow interrupted by long\nnon-browser steps keeps its login state.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / mobile
      Added value: +{
      +  "default": false,
      +  "description": "Mobile device emulation (coarse pointer, no hover) for the initial\nviewport.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / persistent
      Added value: +{
      +  "default": false,
      +  "description": "Persist the login state (cookies + localStorage/sessionStorage +\nviewport + dialog policy) to the server's local store after every\naction. If the session idles out — or the whole server restarts —\nthe next call with the same session_id revives it logged-in\n(storageState-style recovery, no re-login). Explicit session_close\ndrops the snapshot.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / width
      Added value: +{
      +  "description": "Initial viewport width in CSS pixels. Pinned for the session's life\n(survives navigation) so element rects and media queries anchor to\nthe same layout across every page of the visit.",
      +  "format": "uint32",
      +  "minimum": 0,
      +  "type": [
      +    "integer",
      +    "null"
      +  ]
      +}
  6. Changed2 schema fields changed
    • addedInput schema / properties / storage
      Added value: +{
      +  "description": "Web Storage to inject after the initial navigation lands:\n{\"local_storage\": {\"k\":\"v\"}, \"session_storage\": {\"k\":\"v\"}}. For login\nstates that live in localStorage rather than the cookie jar.\nRound-trips with session_storage."
      +}
    • addedInput schema / properties / ttl_secs
      Added value: +{
      +  "description": "Idle time-to-live in seconds before the session is evicted\n(default: 480, clamped 60..3600). Raise it for long workflows.",
      +  "format": "uint64",
      +  "minimum": 0,
      +  "type": [
      +    "integer",
      +    "null"
      +  ]
      +}
  7. First observed

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No behavioral annotations exist, so the description carries the whole burden, and it does disclose real lifecycle traits: it returns a session_id, idles out after 8 minutes, and with persistent:true survives idle eviction and server restarts (same session_id revives logged-in). It omits operational concerns such as resource/concurrency cost, limits on concurrent sessions, or that explicit session_close is needed to drop the snapshot.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three front-loaded sentences that go purpose -> when to use -> key lifecycle fact, with no padding. The 'persists 8 min idle' and persistent:true sentences are the highest-value facts and are placed last for emphasis without bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, all-optional creator with no output schema, the description covers creation purpose, usage context, the returned session_id, and idle/persistence lifecycle. It would be complete with a pointer to the cleanup/companion tools (session_close, session_list, session_clone) an agent will need next.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 11 parameters (url/start_url alias, account, cookies, storage, ttl_secs, keepalive, persistent, etc.). The description only reiterates the persistent and idle-time concepts and adds no syntax, alias, or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource ('Create a persistent interactive browser session') with the interaction scope spelled out (clicking, typing, scrolling, reading state across page transitions). It also draws a sharp line against the read-only siblings ('rather than read it once'), so an agent can distinguish it from fetch/search/session_clone without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use with concrete triggers (login flows, forms, pagination, click-through) and an implicit when-not-to (single read). It does not name the alternative tool (fetch, render_markdown, search) that the agent should reach for in the read-once case, so it stops just short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.