---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/mcp-tools
markdown_url: https://steel.dev/docs/reference/mcp-tools.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: MCP tools
description: Look up every tool that the Steel MCP server offers, with its parameters and what it returns.
summary: Look up every tool that the Steel MCP server offers, with its parameters and what it returns.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/cli.md
  - https://steel.dev/docs/reference/commands.md
  - https://steel.dev/docs/reference/proxy-locations.md
  - https://steel.dev/docs/reference/signals.md
  - https://steel.dev/docs/reference/errors.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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](https://steel.dev/docs/control/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. `screenshot` also returns a JPEG image, and `status` and `cancel` return 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.
- `after` makes a change safe to retry. A tool that changes the page takes `after`, the `next` value of the previous result. A call with the same `after` returns the stored result and never runs the change twice.
- `target` names an element: a ref from `snapshot`, such as `e5`, or a CSS selector.
- `tab` names a tab by its ID, such as `t1`, from `session_create`, `tab` or an earlier result.
- A failed call sets `isError` on the result. The text of a failed command starts with `Failed:`, then the error code and message, and often a hint for the next step. [Errors](https://steel.dev/docs/reference/errors) lists the codes.
- `navigate`, `click`, `hover`, `type`, `fill`, `press_key`, `select_option`, `check`, `drag` and `scroll` return 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](https://steel.dev/docs/sessions/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](https://steel.dev/docs/reference/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](https://steel.dev/docs/reference/commands#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`](https://steel.dev/docs/reference/commands#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](https://steel.dev/docs/control/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. |
