MCP tools
Steel's hosted MCP server, at https://mcp.steel.dev/mcp, gives an agent tools to start and end sessions, read and act on pages, and read a session's logs and traces. The tools follow the order in which the server registers them. MCP server explains how to connect a client and sign in.
How the tools work
To read a page, the agent calls scrape. To sign in, click or type, it calls session_create, then snapshot to get refs such as e5, then acts on those refs, and calls session_release at the end. The server sends these instructions to each client that connects.
These rules apply to every tool:
- Results are text.
screenshotalso returns a JPEG image, andstatusandcancelreturn an image when the execution took a screenshot. Text from a web page comes back inside<untrusted-page-content>tags, and the server tells the agent never to follow instructions found there. Page text is cut at 30,000 characters. aftermakes a change safe to retry. A tool that changes the page takesafter, thenextvalue of the previous result. A call with the sameafterreturns the stored result and never runs the change twice.targetnames an element: a ref fromsnapshot, such ase5, or a CSS selector.tabnames a tab by its ID, such ast1, fromsession_create,tabor an earlier result.- A failed call sets
isErroron the result. The text of a failed command starts withFailed:, then the error code and message, and often a hint for the next step. Errors lists the codes. navigate,click,hover,type,fill,press_key,select_option,check,dragandscrollreturn a diff: what changed on the page since the last snapshot.
Sessions
session_create
Starts a cloud browser and returns its session ID, a link to watch it live, its first tab and the first next. The session ends after its time limit, or after 10 minutes without commands. In a client that supports MCP Apps, such as Claude, the result also shows the browser live in the conversation.
| Parameter | Type | Required | Description |
|---|---|---|---|
use_proxy | boolean | No | Route traffic through a Steel residential proxy. |
solve_captcha | boolean | No | Let Steel solve CAPTCHAs automatically. |
profile_id | string, a UUID | No | Start from a saved browser profile. |
persist_profile | boolean | No | Save cookies and storage back to the profile when the session ends. |
use_credentials | boolean | No | Fill logins saved in Steel credentials on matching pages. |
timeout_minutes | integer, 1 to 1440 | No | Hard limit on the session's life. 15 by default, which every plan allows. A longer value than your plan allows fails. |
metadata | object | No | Labels to find the session by later with session_list, such as {"task": "checkout"}. Values are strings, numbers or booleans. Up to 50 keys. Session configuration has the rules. |
session_live_view
Streams a session to the live browser view that session_create shows in an MCP Apps client. The view calls this tool, and the client does not offer it to the agent. It works only while a headful session is live.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to stream. |
session_list
Lists the live sessions that this MCP server created in your project. Each line shows a session's ID, status, release reason, creation time, the client that created it, signals and metadata. The newest session comes first. Read-only.
With a filter on metadata, signals, release_reason, created_after or created_before, it searches every session in the project, live and released, unless status is set.
| Parameter | Type | Required | Description |
|---|---|---|---|
all | boolean | No | Include sessions not created through MCP. |
status | live, released, or failed | No | Only sessions in this state. live by default when no filter is set. |
metadata | object | No | Only sessions whose metadata has all of these exact values. |
signals | array of 1 to 10 signal names | No | Only sessions that carry all of these signals. Signals can arrive after a session ends, so a live session may not have them yet. |
release_reason | user_requested, timeout, inactivity_timeout, creation_timeout, startup_failed, browser_closed, or browser_crashed | No | Only sessions that ended for this reason. |
created_after | string, an ISO 8601 time | No | Only sessions created at or after this time. |
created_before | string, an ISO 8601 time | No | Only sessions created before this time. |
limit | integer, 1 to 50 | No | How many sessions to return. 20 by default. |
cursor | string, a UUID | No | The cursor from a previous result, to list the sessions after it. |
session_release
Ends a session and stops its billing. Its tabs and refs stop working. Calling it again on the same session is safe. The second call says that the session has ended.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to end. |
Web
scrape
Opens a URL in a fresh cloud browser and returns the page as Markdown, with its URL and title. No session is needed, and nothing is left running. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string, a URL | Yes | The page to read. |
use_proxy | boolean | No | Route traffic through a Steel residential proxy. |
Page
Every tool in this section takes session_id, the session to act on. The session must be live. Names in the CLI and the MCP server maps each tool to the command that it sends.
navigate
Opens url in the tab, or goes back, goes forward or reloads. Give either url or action.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
tab | string | Yes | The tab, such as t1. |
url | string | No | The URL to open. |
action | back, forward, or reload | No | What to do instead of opening url. |
snapshot
Returns the page as an accessibility tree, with refs such as e5 for the elements that the agent can act on or point to. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
tab | string | Yes | The tab, such as t1. |
interactive | boolean | No | Only list the elements that have a ref. |
compact | boolean | No | Drop structure that holds no content. |
depth | integer, at least 0 | No | Limit how deep the tree goes. |
click
Clicks the element, or double-clicks it with double.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
target | string | Yes | A ref or a CSS selector. |
double | boolean | No | Double-click instead. |
tab | string | No | The tab, such as t1. |
hover
Moves the mouse over the element, for menus and tooltips.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
target | string | Yes | A ref or a CSS selector. |
tab | string | No | The tab, such as t1. |
type
Types text key by key, as a person would.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
target | string | Yes | A ref or a CSS selector. |
text | string | Yes | The text to type. |
clear | boolean | No | Clear the field first. |
submit | boolean | No | Press Enter after typing. |
tab | string | No | The tab, such as t1. |
fill
Sets the value of one or more fields in order. It stops at the first field that fails.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
fields | array of 1 to 50 objects | Yes | Each object has target, a ref or a CSS selector, and value, a string. |
tab | string | No | The tab, such as t1. |
press_key
Presses a key or chord, such as Enter, Escape, ArrowDown or Control+a, on target or on the focused element. When a dialog is open on the tab, Enter without target accepts it, and Escape dismisses it.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
key | string | Yes | The key or chord. |
target | string | No | A ref or a CSS selector. |
tab | string | No | The tab, such as t1. |
select_option
Selects options by value or by label in a select element.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
target | string | Yes | A ref or a CSS selector. |
values | array of at least 1 string | Yes | The options to select. |
tab | string | No | The tab, such as t1. |
check
Checks a checkbox, a radio button or a switch, or unchecks it with checked set to false.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
target | string | Yes | A ref or a CSS selector. |
checked | boolean | No | true by default. |
tab | string | No | The tab, such as t1. |
drag
Drags source and drops it on target.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
source | string | Yes | The element to drag: a ref or a CSS selector. |
target | string | Yes | The element to drop it on: a ref or a CSS selector. |
tab | string | No | The tab, such as t1. |
scroll
Scrolls the page, or the content of target, such as a list or a panel.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
direction | up, down, left, or right | No | The direction to scroll. |
amount | number, at least 1 | No | Pixels to scroll. |
target | string | No | A ref or a CSS selector. |
tab | string | No | The tab, such as t1. |
wait
Waits for an element state, text, a URL, a load state, a download, or a fixed time. Give one of them. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
tab | string | No | The tab, such as t1. |
target | string | No | A ref or a CSS selector. |
state | visible, hidden, attached, or detached | No | The state of target to wait for. |
text | string | No | Text to appear on the page. |
url | string | No | Text that the tab's URL must contain, or a pattern with *. See wait in the Commands reference. |
load | load, domcontentloaded, or networkidle | No | A load state to reach. |
ms | integer, 0 to 30000 | No | A fixed wait, in milliseconds. |
download | boolean | No | Wait for a download to finish. |
timeout | integer, 0 to 50000 | No | Milliseconds before giving up. |
get
Reads text, HTML, Markdown, a field's value, an attribute, a count or a bounding box from target, or the title or URL of the tab. Without target, markdown reads the main content of the page. With what set to locator, it lists ways to find target again in a later session, best first, for code that calls Commands. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
what | text, html, markdown, value, attr, title, url, count, box, or locator | Yes | What to read. |
target | string | No | A ref or a CSS selector. Required for every what except markdown, title and url. count takes a CSS selector, not a ref. |
attribute | string | No | The attribute to read, with what set to attr. |
tab | string | No | The tab, such as t1. |
find
Finds elements by role, text, label, placeholder, alt text, title, test ID or CSS selector, and returns their refs. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
by | role, text, label, placeholder, alt, title, testid, or css | Yes | How to find the elements. |
value | string | Yes | What to look for. |
name | string | No | The accessible name, with by set to role. |
exact | boolean | No | Match the whole text. |
tab | string | No | The tab, such as t1. |
screenshot
Captures the visible part of the tab, the full page or target, and returns it as a JPEG image.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | No | The next from the previous result. |
target | string | No | A ref or a CSS selector. |
full_page | boolean | No | Capture the whole page. |
tab | string | No | The tab, such as t1. |
eval
Runs a script in the tab and returns its value. Use it to extract data that the other tools do not reach.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
after | string | Yes | The next from the previous result. |
tab | string | Yes | The tab, such as t1. |
script | string | Yes | An expression or a function body. Its value is returned. |
timeout | integer, 0 to 50000 | No | Milliseconds before giving up. |
tab
Lists the tabs, opens a new one, at url if given, or closes tab.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
action | list, new, or close | Yes | What to do. |
after | string | No | The next from the previous result. Required to open or close a tab. |
tab | string | No | The tab to close. |
url | string | No | The URL to open in the new tab. |
status
Waits for an execution that is still running, and returns its result. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
execution | string | Yes | The ID of the running execution, from an earlier result. |
cancel
Stops an execution that is still running.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | The session to act on. |
execution | string | Yes | The ID of the running execution, from an earlier result. |
Logs
These tools read a session that is running or that has ended.
session_logs
Returns the newest console messages, page errors and page loads of a session, in time order. Add network to types to see every request and response with its status code. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string, a UUID | Yes | The session to read. |
types | array of 1 or more of console, errors, network, navigation | No | Which events to return. console, errors and navigation by default. |
since | string, an ISO 8601 time | No | Only events at or after this time. |
until | string, an ISO 8601 time | No | Only events at or before this time. |
limit | integer, 1 to 200 | No | How many of the newest events to return. 100 by default. |
session_traces
Returns the newest clicks, key presses, form fills and page loads of a session, in time order. It includes actions taken outside the MCP server, for example by your own scripts. Each step names its element with a CSS selector, so that a script can repeat it. Typed text is never shown, only its length. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string, a UUID | Yes | The session to read. |
since | string, an ISO 8601 time | No | Only events at or after this time. |
until | string, an ISO 8601 time | No | Only events at or before this time. |
limit | integer, 1 to 200 | No | How many of the newest events to return. 100 by default. |