CrawlForge MCP Server

browser_session

Maintain a live browser page with cookies and login across calls to open a URL, snapshot interactive refs, act stepwise, read content, and close.

Instructions

Use this to drive a browser across several calls, keeping the page, its cookies and its login in between. The loop is: open a session on a URL, snapshot it to list the interactive elements with stable refs (@e1, @e2 ..., including elements inside open shadow roots and iframes), act on those refs, read the content, close. Because the page stays open you can look before each step instead of committing to a whole chain up front, so a wrong selector costs one call rather than all of them. Operations: open (url, stealth, engine, ttl, activity_ttl, viewport), snapshot, act (the same action array as scrape_with_actions), read (formats; the whole page by default, onlyMainContent:true for the main article block alone), screenshot, close, list. Navigation invalidates refs, so snapshot again after one. robots.txt is respected on every navigation, and screenshots are stored as crawlforge://screenshot/{actionId} resources. A session expires 600s after it opens or 300s after its last use, whichever comes first, so close it when you are done. Not for a page that renders without interaction (scrape), and not for an interaction you can write out in advance - that is one scrape_with_actions call for 5. Cost: 3 credits to open; read 2; snapshot, act, screenshot, close and list 1 each. Example: browser_session({operation:"open", url:"https://app.com/login"}), then browser_session({operation:"snapshot", session_id:"..."})

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ttl`	No	open: seconds the session may live at most (default 600)
`url`	No	open: the URL to load the session on
`engine`	No	open: stealth engine for the session, with stealth:true. "auto" (default) runs camoufox when it is installed and Chromium otherwise; every operation echoes the `engine` that actually ran. "camoufox" is Firefox-based with a higher anti-detect score; "chromium" (= "playwright") forces Chromium. Refused without stealth:true, where the browser is always Chromium.	auto
`format`	No	screenshot: image format	png
`actions`	No	act: the action array, same shape as scrape_with_actions. Target refs like "@e2" in `selector`
`formats`	No	read: output formats
`quality`	No	screenshot: JPEG quality
`stealth`	No	open: run the session in the stealth browser
`timeout`	No	Per-action timeout in ms
`selector`	No	screenshot: capture just this element (a ref like "@e2" works)
`viewport`	No	open: viewport size
`full_page`	No	screenshot: capture the full scrollable page
`max_nodes`	No	snapshot: cap on emitted nodes (default 200)
`operation`	Yes	open a session, observe it, act on it, read it, or close it
`session_id`	No	The id returned by operation:"open". Required by every operation except open and list
`activity_ttl`	No	open: seconds the session may sit idle (default 300)
`respect_robots`	No	Respect the target site's robots.txt (default: true). Setting this to false is honoured, returns a warning in the response, and is recorded against your API key — it is your decision, not a silent default.
`onlyMainContent`	No	read: false (default) returns the whole page as markdown/text (markdown leaves out nav, footer and aside elements, as scrape's does; text leaves out nothing); true keeps only the main article block via Readability, which drops navigation and footers but can also drop list items on listing and app pages. The result's extractionMethod says which ran ("full_page" for the whole page)
`interactive_only`	No	snapshot: only interactive elements get refs (false also emits headings and landmarks)
`max_inline_chars`	No	Largest result to return inline, in characters of its JSON. Over it, the call returns a preview plus a result_handle for read_result instead of the whole result (default 40,000; env CRAWLFORGE_MAX_INLINE_CHARS)
`continue_on_error`	No	act: keep going past a failed action

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv6.18.1Oct 3, 2026

addedInput schema / properties / onlyMainContent

Added value: +{
+  "default": false,
+  "description": "read: false (default) returns the whole page as markdown/text (markdown leaves out nav, footer and aside elements, as scrape's does; text leaves out nothing); true keeps only the main article block via Readability, which drops navigation and footers but can also drop list items on listing and app pages. The result's extractionMethod says which ran (\"full_page\" for the whole page)",
+  "type": "boolean"
+}

Changed1 schema field changedv6.8.0Sep 23, 2026

addedInput schema / properties / engine

Added value: +{
+  "default": "auto",
+  "description": "open: stealth engine for the session, with stealth:true. \"auto\" (default) runs camoufox when it is installed and Chromium otherwise; every operation echoes the `engine` that actually ran. \"camoufox\" is Firefox-based with a higher anti-detect score; \"chromium\" (= \"playwright\") forces Chromium. Refused without stealth:true, where the browser is always Chromium.",
+  "enum": [
+    "auto",
+    "chromium",
+    "camoufox",
+    "playwright"
+  ],
+  "type": "string"
+}

Addedv6.6.0Sep 13, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description discloses non-obvious behavior: sessions expire 600s after open or 300s after last use, navigation invalidates refs so you must snapshot again, robots.txt is respected on every navigation, screenshots are stored as crawlforge:// resources, and per-operation credit costs. This is substantial disclosure the annotations cannot carry.

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?

Despite covering seven operations and 21 parameters, the description is front-loaded with the core loop and the exclusion rule, then layers in cost, expiry, and a worked example. Every sentence is load-bearing — no filler restating the name or schema.

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

Completeness5/5

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

For a stateful, multi-operation, open-world tool with no output schema, it covers the lifecycle (open→snapshot→act→read→close), TTL constraints, ref invalidation, robots.txt handling, output-handle behavior (via schema), and cost. Nothing an agent needs to drive it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema can't: it groups parameters by operation (open takes url/stealth/engine/ttl/activity_ttl/viewport; read takes formats with onlyMainContent behavior), explains the @e1 ref targeting model, and notes refs include shadow-root and iframe elements. That is real value beyond the structured fields.

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?

The description states a specific verb+resource (drive a browser across several calls, keeping page/cookies/login) and enumerates the exact operation set (open, snapshot, act, read, screenshot, close, list). It explicitly distinguishes itself from the two siblings it could be confused with — scrape for pages that need no interaction and scrape_with_actions for a pre-writable chain.

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

Usage Guidelines5/5

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

It gives explicit when-to-use ('look before each step instead of committing to a whole chain') and when-not-to-use ('Not for a page that renders without interaction (scrape), and not for an interaction you can write out in advance - that is one scrape_with_actions call'), naming the alternatives and the selecting condition. The one-call-vs-whole-chain cost framing makes the tradeoff concrete.

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

browser_session

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools