--- title: "MCP Tool Reference" description: "Reference for the Shiplight MCP server's browser sessions, page inspection, actions, debugging, evidence reports, browser options, and configuration." --- # MCP Tool Reference
The Shiplight MCP server lets your coding agent drive a real browser: open or attach to a session, inspect pages, perform actions, capture evidence, and read console and network logs. The server does not require an LLM API key. Your coding agent handles the reasoning; Shiplight executes the browser operations. Package: [`@shiplightai/mcp`](https://www.npmjs.com/package/@shiplightai/mcp). Always run latest via `npx -y @shiplightai/mcp@latest`. No manual update step. Install it once per agent. See [Quick Start](/getting-started/quick-start). This page covers the tools and their main parameters. For task-focused instructions and example prompts, see [Guides](/guides/). ## How It Works Your agent usually follows this sequence: **start → inspect → act → verify → close → report** 1. **Start** — `new_session` opens Chromium. `attach_to_browser` connects to a browser that is already running. Both return a `session_id` for the other tools. 2. **Load the action schema** — after starting or attaching, the agent reads the `shiplight://schemas/action-entity` MCP resource for the current `act` parameters. 3. **Inspect** — `inspect_page` saves a DOM snapshot and a matching Set-of-Mark screenshot. The DOM includes element indices for actions. 4. **Act** — `act` performs one or more browser actions using those element indices. 5. **Verify** — the agent inspects the resulting page and can check console or network logs when needed. 6. **Close and report** — `close_session` saves the video and Playwright trace for a recorded session. `generate_html_report` then builds a local evidence report. ## Tools ### Sessions and Connections | Tool | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `new_session` | Open Chromium with optional emulation, a persistent profile, an extension, restored storage, or evidence recording | | `attach_to_browser` | Connect through a CDP URL or the Shiplight Chrome extension relay. See [Attach to your browser](/guides/attach-to-your-browser) | | `save_storage_state` | Save cookies, local storage, and IndexedDB to a file for use in a later `new_session` | | `close_session` | Close one session and return its evidence paths. Omit `session_id` to close all open sessions | `new_session` accepts a rich set of `browser_options`: viewport, mobile emulation, color scheme, locale, geolocation, proxy, persistent profile, and more. See [Browser Options](#browser-options) below for the full list. ### Navigation and Inspection | Tool | Description | | --------------- | --------------------------------------------------------------------------------------------------------------- | | `navigate` | Open a URL. If `url` is omitted, return the current URL without navigating | | `get_page_info` | Return the current URL and page title without taking a screenshot | | `inspect_page` | Save a DOM snapshot and matching Set-of-Mark screenshot, then return their file paths | | `get_locators` | Return Playwright locators, XPath, frame paths, tags, and text for up to 50 element indices from `inspect_page` | ### Actions | Tool | Description | | ----- | ----------------------------------------------------------------------------------------------------------------------- | | `act` | Run one or more actions. Each action needs a plain-language description and any parameters defined by the action schema | `act` supports these actions: | Category | Actions | | ------------- | ----------------------------------------------------------------------------------- | | Pointer | `click`, `double_click`, `right_click`, `hover` | | Text and keys | `input_text`, `clear_input`, `press` | | Forms | `select_dropdown_option`, `get_dropdown_options`, `set_date_for_native_date_picker` | | Scrolling | `scroll`, `scroll_to_text`, `scroll_on_element` | | Navigation | `go_to_url`, `go_back`, `reload_page` | | Tabs | `switch_tab`, `close_tab` | | Waiting | `wait`, `wait_for_download_complete` | | Files | `upload_file` | | Values | `save_variable` | The action schema is the source of truth for required fields such as `element_index`, `keys`, file paths, and timeouts. MCP clients can read it from `shiplight://schemas/action-entity`. ### Debugging | Tool | Description | | -------------------------- | --------------------------------------------------------------------------------------------- | | `get_browser_console_logs` | Return the latest 100 console entries, optionally filtered by timestamp and log type | | `get_browser_network_logs` | Return the latest 100 requests, optionally filtered by timestamp or HTTP success/error status | ### Reporting | Tool | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | | `generate_html_report` | Build a self-contained local HTML report from a closed session that was started with `record_evidence: true` | The report can include a title, summary, acceptance checks, highlighted steps, video, and Playwright trace. Pass the paths returned by `close_session`; `output_path` defaults to `/tmp/report.html`. ## Browser Options The `new_session` tool accepts `browser_options` to control viewport, emulation, extensions, and more. Your AI coding agent uses these parameters automatically based on your instructions. ### All Browser Options | Option | Type | Description | Default | | ------------------- | --------- | ----------------------------------------------------------------- | ---------- | | `viewport` | `object` | `{ width, height }` in pixels | 1280 × 720 | | `is_mobile` | `boolean` | Emulate mobile device behavior (CSS media queries, meta viewport) | `false` | | `has_touch` | `boolean` | Enable touch events | `false` | | `user_agent` | `string` | Custom user agent string | — | | `color_scheme` | `string` | `"light"`, `"dark"`, or `"no-preference"` | `"light"` | | `timezone_id` | `string` | Timezone ID (e.g., `"America/New_York"`) | — | | `geolocation` | `object` | `{ latitude, longitude, accuracy? }` | — | | `locale` | `string` | Browser locale (e.g., `"en-US"`, `"ja-JP"`) | — | | `disable_security` | `boolean` | Disable web security (CORS, CSP) | `false` | | `record_evidence` | `boolean` | Enable video and trace recording | `false` | | `headless` | `boolean` | Run browser in headless mode | `false` | | `proxy` | `object` | `{ server, username?, password? }` | — | | `path_to_extension` | `string` | Path to unpacked Chrome extension directory | — | | `user_data_dir` | `string` | Chrome user data directory for persistent profile | — | ### Top-Level Options These are passed alongside `browser_options`, not inside it: | Option | Type | Description | | -------------------- | -------- | --------------------------------------------------------------- | | `starting_url` | `string` | URL to navigate to on session creation (default: `about:blank`) | | `storage_state_path` | `string` | Path to storage state file to restore cookies/localStorage | ## Configuration The server keeps environment variables already supplied by the MCP client or inherited from its host process. It then loads a `.env` file from its current working directory as a fallback. Values in `.env` do not override existing values. ### Common Environment Variables | Variable | Description | | ----------------------------- | --------------------------------------------------------------- | | `SHIPLIGHT_RELAY_PORT` | Port for the Chrome extension relay used by `attach_to_browser` | | `TERMINATION_TIMEOUT` | Session termination timeout in milliseconds | | `SHIPLIGHT_ACTION_INDICATORS` | Set to `1` to show an on-page indicator before each action | | `LOG_LEVEL` | Server log level: `ERROR`, `WARN`, `INFO` (default), or `DEBUG` | | `SHIPLIGHT_TELEMETRY` | Set to `0` to disable anonymous usage telemetry | | `DO_NOT_TRACK` | Set to `1` to disable anonymous usage telemetry | The current server enables `PWDEBUG=console` automatically so generated action data can include semantic Playwright locators. For install steps, including manual MCP config for agents [`add-mcp`](https://www.npmjs.com/package/add-mcp) doesn't cover, see [Quick Start](/getting-started/quick-start#manual-mcp-config).