Mithwire MCP

session_start

Launch an isolated browser session for automation, with optional persistent profiles, proxies, headless mode, and cookie injection. Ensures proxy-aligned identity and blocks WebRTC leaks.

Instructions

Launch a new, isolated browser. By default it is ephemeral (no saved state) and headful. Pass profile= to launch a persistent managed profile whose cookies/storage survive across runs. Optional: headless, proxy, proxy_ref, start_url, cookie_file (one-shot cookie injection). engine selects the browser engine: 'cdp' (default) uses the system Chrome with Mithwire CDP/JS patches; 'stealth' uses a CloakBrowser binary with C++ source-level fingerprint patches for zero-lie stealth (requires pip install mithwire-mcp[stealth]). On unsupported platforms, 'stealth' falls back to 'cdp' with a warning. proxy accepts 'http://host:port', 'http://user:pass@host:port', the provider 'scheme:host:port:user:pass' form, or socks5://host:port (authenticated SOCKS not wired yet; use the HTTP endpoint). It can ALSO be a dict {server, username?, password?, rotation_url?} where rotation_url is an optional provider endpoint that rotates the upstream exit IP when hit. proxy_ref is the alternate form: a name pointing at an entry in the proxy registry (see session_proxy_set). The two are mutually exclusive per session — a literal proxy spec wins over a registry reference. When a proxy is set, the session is REFUSED if the proxy fails a pre-launch reachability + credentials probe (no half-launched browser, no fallback to the host's direct connection). On success, the browser identity defaults to the proxy egress (timezone, locale/languages, Accept-Language, geolocation) so the two never disagree; any field set in fingerprint={...} or in the profile's launch_options wins over the proxy default. Pass fingerprint={...} to override any identity field explicitly (timezone_id, languages, latitude/longitude, user_agent, platform, hardware_concurrency, device_memory, screen, webgl_vendor/webgl_renderer); see session_set_fingerprint. webrtc_leak_protection controls the WebRTC IP-leak guard: 'auto' (default; filters public ICE candidates when proxied so the real IP can't leak via STUN), 'filter' (always filter), 'disable' (remove RTCPeerConnection), or 'off'. skip_probe (default false): skip the pre-launch proxy health check entirely. Useful when the proxy has already been verified externally or when the proxy does not support the HTTPS CONNECT tunnel used by the default probe. Identity defaults (timezone, locale) will be derived via an in-browser lookup after launch. probe_timeout (seconds): override the default 8-second proxy probe timeout. Raise for slow residential/mobile proxies; the probe includes an automatic plain-HTTP fallback for proxies that fail the primary HTTPS/CONNECT path.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`proxy`	No
`engine`	No
`profile`	No
`sandbox`	No
`headless`	No
`proxy_ref`	No
`start_url`	No
`session_id`	No
`skip_probe`	No
`cookie_file`	No
`fingerprint`	No
`browser_args`	No
`probe_timeout`	No
`cookie_fallback_domain`	No
`webrtc_leak_protection`	No
`browser_executable_path`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.5.1Oct 18, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so exceptionally: it discloses that a proxy failure REFUSES the session with no half-launched browser and no fallback to the host's direct connection, that identity defaults derive from proxy egress, that fingerprint/profile launch_options win over those defaults, the stealth-to-cdp fallback on unsupported platforms, and the WebRTC guard's four modes. This is exactly the failure-mode and safety context an agent needs.

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

Conciseness4/5

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

It is front-loaded with purpose and mode selection, and nearly every sentence carries parameter or behavioral information that is otherwise absent from the schema. It is a single dense block rather than segmented, which mildly hurts scanability, but the length is largely justified by 16 undocumented parameters.

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?

An output schema exists, so return values need no explanation, and the description covers the high-stakes behaviors (proxy probe/refusal, identity derivation, WebRTC guard). It is nearly complete for a launch tool, with the residual gap being the five unmentioned parameters.

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 0% and there are 16 parameters, so the description must compensate; it explains most core parameters in depth, including the four accepted proxy string formats, the proxy dict shape with rotation_url, the engine values and install requirement, and the enumerable fingerprint fields. However, sandbox, session_id, browser_args, cookie_fallback_domain, and browser_executable_path are never mentioned, leaving five parameters undocumented anywhere.

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 opening sentence gives a specific verb and resource ('Launch a new, isolated browser') and immediately states the two operating modes (ephemeral by default, persistent when profile is passed). It clearly distinguishes the tool from siblings like session_stop, session_get, and session_profile_set, which are referenced by name for their own concerns.

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?

It gives actionable usage conditions: pass profile=<name> for persistence, skip_probe when the proxy was verified externally or lacks CONNECT support, raise probe_timeout for slow residential/mobile proxies, and it routes fingerprint overrides to session_set_fingerprint and registry entries to session_proxy_set. It lacks an explicit 'use this vs. alternatives' framing for the tool as a whole, but no alternative launcher exists, so the guidance is strong.

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

Deploy Server