MCP Tool Reference

View as Markdown

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. Always run latest via npx -y @shiplightai/mcp@latest. No manual update step. Install it once per agent. See Quick Start.

This page covers the tools and their main parameters. For task-focused instructions and example prompts, see 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
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 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 doesn't cover, see Quick Start.