From a791541e8c900b69b33444de8e7507be315996fe Mon Sep 17 00:00:00 2001 From: junhsss Date: Thu, 5 Nov 2026 01:47:06 +0900 Subject: [PATCH 1/2] docs: add the Steel MCP server --- content/docs/cookbook/topics/mcp.mdx | 2 +- content/docs/overview/authentication.mdx | 9 + .../docs/overview/commands-api/overview.mdx | 1 + content/docs/overview/intro-to-steel.mdx | 4 + content/docs/overview/mcp.mdx | 393 ++++++++++++++++++ content/docs/overview/meta.json | 1 + .../steel-local-vs-steel-cloud.mdx | 1 + content/docs/overview/skills/index.mdx | 10 + lib/agent-instructions.ts | 6 + scripts/sync-cookbook.ts | 1 + 10 files changed, 427 insertions(+), 1 deletion(-) create mode 100644 content/docs/overview/mcp.mdx diff --git a/content/docs/cookbook/topics/mcp.mdx b/content/docs/cookbook/topics/mcp.mdx index 66ed0f4f..88778769 100644 --- a/content/docs/cookbook/topics/mcp.mdx +++ b/content/docs/cookbook/topics/mcp.mdx @@ -1,6 +1,6 @@ --- title: MCP -description: 1 recipe tagged MCP. +description: Recipes that build your own MCP server on Steel. For the hosted Steel MCP server, connect a client to mcp.steel.dev instead. --- diff --git a/content/docs/overview/authentication.mdx b/content/docs/overview/authentication.mdx index f20bad1d..669218e6 100644 --- a/content/docs/overview/authentication.mdx +++ b/content/docs/overview/authentication.mdx @@ -146,6 +146,15 @@ steel login This walks you through signing in and stores a key locally. Alternatively, set `STEEL_API_KEY` in your environment and the CLI will use it directly: useful for CI and non-interactive environments. +#### MCP Server + +The [Steel MCP server](/overview/mcp) can sign you in with OAuth, so a client can connect without a key. To use a key instead, send it as a bearer token: + +```bash Terminal -wcn +claude mcp add --transport http steel https://mcp.steel.dev/mcp \ + --header "Authorization: Bearer $STEEL_API_KEY" +``` + ### Managing Your API Keys All key management happens in the [API Keys dashboard](https://app.steel.dev/settings/api-keys). From there you can: diff --git a/content/docs/overview/commands-api/overview.mdx b/content/docs/overview/commands-api/overview.mdx index c796b07c..9d281a27 100644 --- a/content/docs/overview/commands-api/overview.mdx +++ b/content/docs/overview/commands-api/overview.mdx @@ -52,6 +52,7 @@ Send a ref back to act on its element. Pass `next` as `after`, so Steel knows wh | Approach | Use it for | | --- | --- | | Commands API | Agents that read the page and act step by step. Plain HTTP, no browser library. | +| [MCP Server](/overview/mcp) | Agents in an MCP client, such as Claude or Cursor. The same commands as tools, with nothing to host. | | [Playwright](/cookbook/playwright) or [Puppeteer](/cookbook/puppeteer) | Scripts that need full CDP control, such as network interception. | | [Browser Tools](/overview/browser-tools/overview) | One-shot scrapes, screenshots, and PDFs without a session. | diff --git a/content/docs/overview/intro-to-steel.mdx b/content/docs/overview/intro-to-steel.mdx index 3604f02f..ee1fe9c6 100644 --- a/content/docs/overview/intro-to-steel.mdx +++ b/content/docs/overview/intro-to-steel.mdx @@ -71,6 +71,10 @@ Under the hood, Steel’s cloud-native platform handles all the headaches of bro - [Connect with Playwright](/cookbook/playwright) - [Connect with Selenium](/cookbook/selenium) +### Use Steel from an AI client + +- [Steel MCP Server](/overview/mcp) + ### Reference - [API Reference](/api-reference) diff --git a/content/docs/overview/mcp.mdx b/content/docs/overview/mcp.mdx new file mode 100644 index 00000000..d8938d4b --- /dev/null +++ b/content/docs/overview/mcp.mdx @@ -0,0 +1,393 @@ +--- +title: Steel MCP Server +sidebarTitle: MCP Server +description: Connect Claude, Cursor, VS Code, Codex, or any MCP client to Steel cloud browsers with the hosted Steel MCP server. Read pages, or drive a browser session with tools such as snapshot, click, and fill. +llm: true +publishedAt: "2026-11-05" +--- + +The Steel MCP server gives any MCP client cloud browsers. An agent can read a page in one call, or start a session and click, type, and fill forms in a real browser. Steel hosts the server, so there is nothing to install or run. + +:::callout +type: info +### Beta +The MCP server is in beta. Tools, fields, and limits may change. Share feedback on [Discord](https://discord.gg/steel-dev). +::: + +```bash Claude Code -wcn +claude mcp add --transport http steel https://mcp.steel.dev/mcp +``` + +The first time the client connects, it opens a Steel sign-in page. Sign in and pick the project the agent should work in. Then ask for something that needs a browser: + +```text Prompt -wcn +Use Steel to open news.ycombinator.com and list the top five stories. +``` + +### Connect a client + +The server URL is `https://mcp.steel.dev/mcp`. Add it to your client as a remote MCP server: + + + +```bash !! Claude Code -wcn +claude mcp add --transport http steel https://mcp.steel.dev/mcp +``` + +```json !! Cursor -wcn +{ + "mcpServers": { + "steel": { + "url": "https://mcp.steel.dev/mcp" + } + } +} +``` + +```json !! VS Code -wcn +{ + "servers": { + "steel": { + "type": "http", + "url": "https://mcp.steel.dev/mcp" + } + } +} +``` + +```toml !! Codex -wcn +[mcp_servers.steel] +url = "https://mcp.steel.dev/mcp" +``` + + + +| Client | Where the config goes | How to sign in | +| --- | --- | --- | +| Claude Code | Run the command in a terminal. | Run `/mcp` in Claude Code and sign in to `steel`. | +| Cursor | `~/.cursor/mcp.json` | Follow Cursor's sign-in prompt. | +| VS Code | `.vscode/mcp.json` in your workspace | Follow VS Code's sign-in prompt. | +| Codex | `~/.codex/config.toml` | Run `codex mcp login steel`. | + +In Claude on the web or the desktop app, open the **Connectors** settings, choose **Add custom connector**, and paste the server URL. Any other client that supports remote MCP servers over Streamable HTTP works the same way. + +### Sign in + +Steel signs clients in with OAuth. Clients find the sign-in page on their own: the server answers a request without credentials with `401` and points to its OAuth metadata. + +```http 401 response -wcn +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Bearer realm="steel", resource_metadata="https://mcp.steel.dev/.well-known/oauth-protected-resource/mcp", scope="mcp:browser" +``` + +On the consent page, pick the organization and one project. Sessions the agent creates run in that project. + +- The approval covers that one project. To switch projects, sign in again and pick another one. +- The client refreshes its access on its own, so you sign in once. +- If your organization requires two-step verification, set it up before you connect. +- Sign-in needs a client that supports Client ID Metadata Documents, from the MCP authorization spec. If your client can't sign in, [use an API key](#use-an-api-key). + +### Use an API key + +Send a Steel API key as a bearer token when your client can't sign in, or when the agent runs unattended, such as in CI. Steel accepts the key, so the client skips the sign-in. + + + +```bash !! Claude Code -wcn +claude mcp add --transport http steel https://mcp.steel.dev/mcp \ + --header "Authorization: Bearer $STEEL_API_KEY" +``` + +```json !! Cursor -wcn +{ + "mcpServers": { + "steel": { + "url": "https://mcp.steel.dev/mcp", + "headers": { + "Authorization": "Bearer ${env:STEEL_API_KEY}" + } + } + } +} +``` + +```json !! VS Code -wcn +{ + "inputs": [ + { + "type": "promptString", + "id": "steel-api-key", + "description": "Steel API key", + "password": true + } + ], + "servers": { + "steel": { + "type": "http", + "url": "https://mcp.steel.dev/mcp", + "headers": { + "Authorization": "Bearer ${input:steel-api-key}" + } + } + } +} +``` + +```toml !! Codex -wcn +[mcp_servers.steel] +url = "https://mcp.steel.dev/mcp" +bearer_token_env_var = "STEEL_API_KEY" +``` + + + +Sessions then run in the key's project. The server also accepts the key in the `steel-api-key` header. Create a key in [API Keys](https://app.steel.dev/settings/api-keys). + +### How the tools work + +The server tells the agent how to use its tools when it connects. The agent takes one of two paths: + +| Task | Tools | +| --- | --- | +| Read a page | `scrape` opens the URL in a fresh browser and returns Markdown. No session, and nothing is left running. | +| Log in, click, type, or fill forms | `session_create`, then `snapshot` and actions on refs, then `session_release`. | + +`session_create` starts a browser. It returns the session id, a link to watch it live, the first tab, and the first `next`: + +```text session_create -wcn +session_id: 5b2c7c1e-3f4a-4d0e-9a8b-2c6f1e0d9a47 +Watch it live: https://app.steel.dev/sessions/5b2c7c1e-3f4a-4d0e-9a8b-2c6f1e0d9a47 +It ends after 60 minutes, or after 10 minutes without commands. +next: op_a1b2c3d4e5 (pass it as after with your first change) + +tab t1: about:blank — + +``` + +`snapshot` returns the page as an accessibility tree. Each element the agent can act on has a ref, such as `e2`: + +```text snapshot -wcn +next: op_k3m5p7r9t1 (pass it as after with your next change) + +tab t1: https://shop.example.com/ — Example Shop +- heading "Find a product" [level=1, ref=e1] +- searchbox "Search" [ref=e2] +- button "Search" [ref=e3] + +``` + +Tools that change the page take `after`, the `next` from the previous result. Here the agent types into the search box and presses Enter: + +```json type -wcn +{ + "session_id": "5b2c7c1e-3f4a-4d0e-9a8b-2c6f1e0d9a47", + "after": "op_k3m5p7r9t1", + "target": "e2", + "text": "mechanical keyboard", + "submit": true +} +``` + +- **Safe retries.** A repeated call with the same `after` returns the stored result. It never runs twice. +- **Page changes.** If the page changed since that `next`, the result says so. The agent takes a new snapshot before it uses old refs. +- **Untrusted text.** Page text comes back inside ``. The server tells the agent never to follow instructions found there. Results are cut at 30,000 characters. +- **Dialogs.** Steel never answers a dialog on its own. The result names the dialog, and the agent answers it with `dialog`. +- **Long calls.** A call that is still running returns an execution id. The agent waits for it with `status` or stops it with `cancel`. + +### Tools + +Every tool except `scrape`, `session_create`, and `session_list` takes a `session_id`. Element tools take a `target`: a ref such as `e5`, or a CSS selector. + +#### Sessions and scraping + +| Tool | Arguments | What it does | +| --- | --- | --- | +| `scrape` | `url`, `use_proxy` | Reads a page without a session and returns it as Markdown. | +| `session_create` | See [Session options](#session-options) | Starts a browser session. | +| `session_list` | `all` | Lists running sessions created through MCP. Set `all` to add sessions created any other way. | +| `session_release` | `session_id` | Ends a session and stops its billing. | + +#### Reading the page + +| Tool | Arguments | What it does | +| --- | --- | --- | +| `snapshot` | `tab`, `interactive`, `compact`, `depth` | Returns the accessibility tree with refs. `interactive` keeps only elements you can act on. | +| `find` | `by`, `value`, `name`, `exact`, `tab` | Finds elements by `role`, `text`, `label`, `placeholder`, `alt`, `title`, `testid`, or `css`, and returns their refs. | +| `get` | `what`, `target`, `attribute`, `tab` | Reads `text`, `html`, `markdown`, `value`, `attr`, `title`, `url`, `count`, `box`, or `locator`. | +| `screenshot` | `target`, `full_page`, `tab` | Captures the tab, the full page, or one element as an image. | +| `wait` | `target`, `state`, `text`, `url`, `load`, `ms`, `download`, `timeout`, `tab` | Waits for an element state, text, a URL, a load state, a download, or a fixed time. | + +#### Acting on the page + +These tools take `after`. + +| Tool | Arguments | What it does | +| --- | --- | --- | +| `navigate` | `tab`, `url` or `action` | Opens a URL, or goes `back`, `forward`, or `reload`. | +| `click` | `target`, `double`, `tab` | Clicks an element. `double` double-clicks it. | +| `hover` | `target`, `tab` | Moves the mouse over an element, for menus and tooltips. | +| `type` | `target`, `text`, `clear`, `submit`, `tab` | Types key by key. `clear` empties the field first. `submit` presses Enter after. | +| `fill` | `fields`, `tab` | Sets up to 50 field values in order. Stops at the first field that fails. | +| `press_key` | `key`, `target`, `tab` | Presses a key or chord, such as `Enter`, `Escape`, or `Control+a`. | +| `select_option` | `target`, `values`, `tab` | Selects options in a select by value or label. | +| `check` | `target`, `checked`, `tab` | Checks a checkbox, radio, or switch. `checked: false` unchecks it. | +| `drag` | `source`, `target`, `tab` | Drags `source` and drops it on `target`. | +| `scroll` | `direction`, `amount`, `target`, `tab` | Scrolls the page, or brings `target` into view. | +| `eval` | `tab`, `script`, `timeout` | Runs JavaScript in the page and returns its value. | + +#### Tabs, dialogs, and long calls + +| Tool | Arguments | What it does | +| --- | --- | --- | +| `tab` | `action`, `tab`, `url` | Lists, opens, or closes tabs. Opening and closing take `after`. | +| `dialog` | `dialog_id`, `action`, `text` | Accepts or dismisses an open dialog. `text` answers a prompt. | +| `status` | `execution` | Waits for a running execution and returns its result. | +| `cancel` | `execution` | Stops a running execution. | + +### Session options + +The agent sets these on `session_create` when your prompt asks for them: + +```json session_create -wcn +{ + "use_proxy": true, + "solve_captcha": true, + "profile_id": "0b7c1d2e-4f5a-4b6c-8d9e-0f1a2b3c4d5e", + "persist_profile": true, + "timeout_minutes": 30 +} +``` + +| Option | Effect | +| --- | --- | +| `use_proxy` | Routes traffic through a Steel residential proxy. | +| `solve_captcha` | Lets Steel solve CAPTCHAs. | +| `profile_id` | Starts from a saved [profile](/overview/profiles-api/overview), by its UUID. | +| `persist_profile` | Saves cookies and storage back to the profile when the session ends. | +| `use_credentials` | Fills logins saved with the [Credentials API](/overview/credentials-api/overview) on matching pages. | +| `timeout_minutes` | The session's hard time limit, from 1 to 1440. Defaults to 60, capped by your plan. | + +### Limits and billing + +MCP sessions and scrapes are regular Steel sessions and scrapes. Sessions bill browser hours, and each `scrape` bills as a Browser Tools call. See [Pricing/Limits](/overview/pricinglimits). + +| Limit | Value | +| --- | --- | +| Session length | 60 minutes by default, capped by your plan. `timeout_minutes` changes it. | +| Idle sessions | A session ends after 10 minutes without a tool call on it. See [Session lifecycle](/overview/sessions-api/session-lifecycle). | +| `scrape` | 20 pages a minute per organization. | +| `session_create` | Your plan's session create rate. | +| Concurrent sessions | Your plan's concurrency limit. | +| Page text | 30,000 characters per result. | + +Ask the agent to release sessions when the task is done. `session_list` shows the ones still running: + +```text session_list -wcn +5b2c7c1e-3f4a-4d0e-9a8b-2c6f1e0d9a47 created 2026-11-05T09:12:44.000Z by mcp +``` + +You can also release sessions from the [Sessions page](https://app.steel.dev/sessions) in the dashboard. + +### Turn a run into a script + +Once the agent has found the right element, `get` with `what: "locator"` lists ways to find it again in a later session, best first: + +```json get -wcn +{ + "session_id": "5b2c7c1e-3f4a-4d0e-9a8b-2c6f1e0d9a47", + "what": "locator", + "target": "e12" +} +``` + +```json Locators -wcn +[ + { + "target": { "role": "button", "name": "Accept", "exact": true }, + "frame": { "css": "iframe[src^=\"https://consent.example.com/?\"]" } + } +] +``` + +Use a locator as the `target` and `frame` of a [Commands API](/overview/commands-api/overview) command. The same step then runs from your code, with no model in the loop: + +```bash curl -wcn +curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \ + -H "steel-api-key: $STEEL_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "commands": [ + { + "command": "click", + "frame": { "css": "iframe[src^=\"https://consent.example.com/?\"]" }, + "target": { "role": "button", "name": "Accept", "exact": true } + } + ] + }' +``` + +### Disconnect a client + +Open **Settings → Profile → Security** in the [dashboard](https://app.steel.dev/settings/profile#/security). Disconnect the client under **Connected apps**. + +- **OAuth clients** lose access within 10 minutes of being disconnected. +- **API keys** stop working when you delete them in [API Keys](https://app.steel.dev/settings/api-keys). + +### Troubleshooting + +Tool errors start with `Failed:` and a code. Most results also tell the agent what to do next. + +| Code | What to do | +| --- | --- | +| `invalid_operation_token` | Steel no longer knows the `after`. Use the `next` from the latest result. | +| `session_ended` | The session is over. Start a new one with `session_create`. | +| `session_not_found` | Check `session_id`, or start a session with `session_create`. | +| `browser_restarted` | Every tab and ref changed. Start again with `tab` and `snapshot`. | +| `stale_ref` | The element left the page. Take a new snapshot. | +| `missing_capability` | The session's browser is too old for these tools. Start a new session. | +| `delivery_failed` | Steel could not reach the browser. Call again with the same arguments. It will not run twice. | +| `expired`, `queue_full` | The call did not start. Call again with the same arguments. | + +See the [Commands API reference](/overview/commands-api/reference) for every error code. Connection errors come back as HTTP status codes: + +| Message | Fix | +| --- | --- | +| `401` The access token is not valid for this MCP server. | Sign in again from your client. | +| `401` The project this sign-in was approved for no longer exists. | Sign in again and pick another project. | +| `401` with an API key | Check the key in [API Keys](https://app.steel.dev/settings/api-keys), or create a new one. | +| `403` Account suspended | Contact [support@steel.dev](mailto:support@steel.dev). | + +### FAQ + +:::faq +### What is the Steel MCP server? + +A hosted Model Context Protocol server at `https://mcp.steel.dev/mcp`. It gives MCP clients such as Claude, Cursor, VS Code, and Codex tools to read pages and drive Steel cloud browsers, with nothing to install. + +### Which MCP clients work with Steel? + +Any client that supports remote MCP servers over Streamable HTTP. Sign-in uses OAuth with Client ID Metadata Documents. A client that can't sign in that way can send a Steel API key as a bearer token instead. + +### Do I need a Steel API key? + +No. Clients that support OAuth sign in with your Steel account. Use an API key for unattended agents, or for clients that can't sign in. + +### How is MCP usage billed? + +The same as the API. Sessions bill browser hours until they are released or time out, and each `scrape` bills as a Browser Tools call. An MCP session also ends after 10 minutes without a tool call. + +### Should I use the MCP server or Steel Skills? + +Use the MCP server when your client supports MCP and you want browser tools with no setup. Use [Steel Skills](/overview/skills) when a coding agent should run the Steel CLI or write Steel code. + +### Can I self-host the Steel MCP server? + +No. The MCP server runs on Steel Cloud only. To build a server with your own tools, start from the [MCP server recipe](/cookbook/mcp). +::: + +### Next steps + +:::next-steps +- [Commands API](/overview/commands-api/overview): The HTTP API behind the page tools +- [Build your own MCP server](/cookbook/mcp): Your own tools in TypeScript, Python, Rust, or Go +::: diff --git a/content/docs/overview/meta.json b/content/docs/overview/meta.json index 995740b2..fa1b9638 100644 --- a/content/docs/overview/meta.json +++ b/content/docs/overview/meta.json @@ -6,6 +6,7 @@ "intro-to-steel", "authentication", "steel-cli", + "mcp", "need-help", "pricinglimits", "...guides", diff --git a/content/docs/overview/self-hosting/steel-local-vs-steel-cloud.mdx b/content/docs/overview/self-hosting/steel-local-vs-steel-cloud.mdx index b4347d60..38f16879 100644 --- a/content/docs/overview/self-hosting/steel-local-vs-steel-cloud.mdx +++ b/content/docs/overview/self-hosting/steel-local-vs-steel-cloud.mdx @@ -16,6 +16,7 @@ llm: true | Extensions | Supported by loading in `api/extensions/` | Supported by using the Extensions API | | Files | Not supported | Supported by the Files API | | Commands API | Off by default. Set `ENABLE_COMMANDS_API=true` | Supported by the Commands API (beta) | +| MCP Server | Not supported | Hosted at `https://mcp.steel.dev/mcp` (beta) | The defining factor between running Steel locally and using Steel Cloud is concurrency. diff --git a/content/docs/overview/skills/index.mdx b/content/docs/overview/skills/index.mdx index fc52ada8..4c3cdaae 100644 --- a/content/docs/overview/skills/index.mdx +++ b/content/docs/overview/skills/index.mdx @@ -79,6 +79,16 @@ steel scrape https://example.com Restart your agent client after installing new skills so it can discover them. +## Skills or MCP? + +Steel Skills and the [Steel MCP server](/overview/mcp) both give agents Steel browsers. They fit different clients: + +| | Steel Skills | Steel MCP server | +| --- | --- | --- | +| How the agent uses Steel | Follows the skill to run the Steel CLI or write Steel code | Calls tools on a server that Steel hosts | +| Setup | Install a skill and the Steel CLI | Add `https://mcp.steel.dev/mcp` to the client | +| Best for | Coding agents that run commands, such as Claude Code, Cursor, and Codex | Any MCP client, including Claude on the web and the desktop app | + ### FAQ :::faq diff --git a/lib/agent-instructions.ts b/lib/agent-instructions.ts index 7269e4ef..5cd81d17 100644 --- a/lib/agent-instructions.ts +++ b/lib/agent-instructions.ts @@ -15,6 +15,7 @@ export const AGENT_INSTRUCTIONS = `# Steel Documentation - Auth env var: \`STEEL_API_KEY\` - API base URL: \`https://api.steel.dev\` - WebSocket: \`wss://connect.steel.dev?apiKey=&sessionId=\` +- MCP server: \`https://mcp.steel.dev/mcp\` (OAuth sign-in, or \`Authorization: Bearer \`) - API reference: https://steel.apidocumentation.com/api-reference - Brand design language (DESIGN.md): https://docs.steel.dev/DESIGN.md @@ -53,6 +54,11 @@ export const AGENT_INSTRUCTIONS = `# Steel Documentation -d '{"commands": [{"command": "navigate", "url": "https://example.com"}, {"command": "snapshot", "interactive": true}]}' \`\`\` Then send \`{"after": "", "commands": [{"command": "click", "target": "e1"}]}\`. Docs: https://docs.steel.dev/overview/commands-api/overview +- To give an MCP client Steel browsers, add the hosted MCP server. In Claude Code: + \`\`\`bash + claude mcp add --transport http steel https://mcp.steel.dev/mcp + \`\`\` + The client signs in with OAuth on first use. Docs: https://docs.steel.dev/overview/mcp - Python SDK: \`\`\`python from steel import Steel diff --git a/scripts/sync-cookbook.ts b/scripts/sync-cookbook.ts index dfc7ad7d..2cd2bed3 100644 --- a/scripts/sync-cookbook.ts +++ b/scripts/sync-cookbook.ts @@ -49,6 +49,7 @@ const TOPIC_DESCRIPTIONS: Record = { Subagents: 'Multi-agent recipes where a lead orchestrator dispatches parallel subagents, each driving its own Steel browser.', Convex: 'Recipes that run Steel from a Convex backend.', + MCP: 'Recipes that build your own MCP server on Steel. For the hosted Steel MCP server, connect a client to mcp.steel.dev instead.', }; // Display order for language tabs in merged concept pages. Entries not From 274ff98002034ac8b02ca2d767f7c7960f820af9 Mon Sep 17 00:00:00 2001 From: junhsss Date: Thu, 5 Nov 2026 01:59:13 +0900 Subject: [PATCH 2/2] docs: show code blocks hidden by the !! marker --- content/docs/overview/agent-traces/api.mdx | 10 +++--- .../docs/overview/agent-traces/overview.mdx | 4 +-- .../docs/overview/agent-traces/timeline.mdx | 2 +- .../docs/overview/browser-tools/overview.mdx | 4 +-- .../docs/overview/commands-api/overview.mdx | 32 +++++++++---------- .../docs/overview/commands-api/reference.mdx | 8 ++--- 6 files changed, 30 insertions(+), 30 deletions(-) diff --git a/content/docs/overview/agent-traces/api.mdx b/content/docs/overview/agent-traces/api.mdx index c9d9542a..98757455 100644 --- a/content/docs/overview/agent-traces/api.mdx +++ b/content/docs/overview/agent-traces/api.mdx @@ -12,12 +12,12 @@ Use the Agent Traces API when you want the same activity timeline shown in the d Returns the trace timeline for a finished or in-progress session. -```bash !! curl -wcn +```bash curl -wcn curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \ -H "steel-api-key: $STEEL_API_KEY" ``` -```javascript !! fetch -wcn +```javascript fetch -wcn const response = await fetch( `https://api.steel.dev/v1/sessions/${sessionId}/agent-traces`, { headers: { "steel-api-key": process.env.STEEL_API_KEY } }, @@ -28,7 +28,7 @@ const trace = await response.json(); ### Response -```json !! JSON -wcn +```json JSON -wcn { "events": [ { @@ -70,7 +70,7 @@ Activity-specific details appear when relevant. For example, click activities ca When Steel can identify the element involved in an activity, `target` can include readable labels and useful selectors: -```json !! target -wcn +```json target -wcn { "role": "button", "accessibleName": "Sign in", @@ -91,7 +91,7 @@ Use target details as hints for review or replay. Some activities, such as navig You can limit results to a time range: -```bash !! curl -wcn +```bash curl -wcn curl "https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces?startTime=2026-05-22T18:00:00.000Z&endTime=2026-05-22T18:10:00.000Z" \ -H "steel-api-key: $STEEL_API_KEY" ``` diff --git a/content/docs/overview/agent-traces/overview.mdx b/content/docs/overview/agent-traces/overview.mdx index 7af65222..e93f6ce0 100644 --- a/content/docs/overview/agent-traces/overview.mdx +++ b/content/docs/overview/agent-traces/overview.mdx @@ -35,12 +35,12 @@ Agent Traces are based on what happened in the browser session, not on what the Fetch the trace timeline for a session as JSON: -```bash !! curl -wcn +```bash curl -wcn curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \ -H "steel-api-key: $STEEL_API_KEY" ``` -```json !! Response -wcn +```json Response -wcn { "events": [ { diff --git a/content/docs/overview/agent-traces/timeline.mdx b/content/docs/overview/agent-traces/timeline.mdx index aed6e489..291f5410 100644 --- a/content/docs/overview/agent-traces/timeline.mdx +++ b/content/docs/overview/agent-traces/timeline.mdx @@ -71,7 +71,7 @@ The format includes: A trimmed example: -```markdown !! agent-traces.md -wcn +```markdown -wcn agent-traces.md # Browser session Recording of a real browser session, structured for review and replay by an automation agent. diff --git a/content/docs/overview/browser-tools/overview.mdx b/content/docs/overview/browser-tools/overview.mdx index 84f60fee..e1369889 100644 --- a/content/docs/overview/browser-tools/overview.mdx +++ b/content/docs/overview/browser-tools/overview.mdx @@ -66,7 +66,7 @@ The supported formats map to fields on `content`: `metadata` carries the usual SEO fields (`title`, `description`, `canonical`, Open Graph tags, JSON-LD, `statusCode`, etc.) and `links` is a flat array of every anchor on the page. -```json !! JSON -wcn +```json JSON -wcn { "content": { "markdown": "# Steel Docs\n\n..." @@ -142,7 +142,7 @@ print(result.url) The hosted URL is public and durable. Download it like any other PNG: -```typescript !! Typescript -wcn +```typescript Typescript -wcn import fs from "node:fs"; const response = await fetch(result.url); diff --git a/content/docs/overview/commands-api/overview.mdx b/content/docs/overview/commands-api/overview.mdx index 9d281a27..8cff7b4f 100644 --- a/content/docs/overview/commands-api/overview.mdx +++ b/content/docs/overview/commands-api/overview.mdx @@ -14,7 +14,7 @@ type: info The Commands API is in beta. Commands, fields, and limits may change. Share feedback on [Discord](https://discord.gg/steel-dev). ::: -```bash !! curl -wcn +```bash curl -wcn curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \ -H "steel-api-key: $STEEL_API_KEY" \ -H "Content-Type: application/json" \ @@ -28,7 +28,7 @@ curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \ The response has one result per command. The snapshot lists the elements on the page, each with a ref. -```json !! Response -wcn +```json Response -wcn { "next": "op_4f8k2m9q1x", "epoch": 1, @@ -43,7 +43,7 @@ The response has one result per command. The snapshot lists the elements on the Send a ref back to act on its element. Pass `next` as `after`, so Steel knows which page state you saw. -```json !! Request -wcn +```json Request -wcn { "after": "op_4f8k2m9q1x", "commands": [{ "command": "click", "target": "e1" }] } ``` @@ -155,7 +155,7 @@ The click uses a locator, so the example does not depend on a ref number. An age A snapshot is the page's accessibility tree as text. Each line has the role, the name, the states, and a ref. A value follows the colon. -```text !! Snapshot -wcn +```text Snapshot -wcn - heading "Account" [level=1, ref=e1] - textbox "Name" [ref=e2]: Ada - checkbox "Remember me" [checked=false, ref=e3] @@ -175,7 +175,7 @@ A ref points at one element and stays the same across snapshots of the same page Commands that act on an element take a `target`. It can be a ref, a CSS selector, or a locator object. -```json !! Request -wcn +```json Request -wcn { "commands": [ { "command": "fill", "target": "e2", "value": "Ada Lovelace" }, @@ -201,7 +201,7 @@ A locator sets exactly one of these fields: Text matches a case-insensitive substring unless you set `exact: true`. When a locator finds several elements, it uses the only visible one or fails with `ambiguous`, so set `nth` to pick one. For an element inside an iframe, add `frame`: -```json !! Request -wcn +```json Request -wcn { "commands": [ { @@ -218,7 +218,7 @@ Text matches a case-insensitive substring unless you set `exact: true`. When a l `commands` takes up to 50 commands. They run in order and stop at the first failure. Commands that already ran are not undone. Add `observe` to see the page after the commands. -```json !! Request -wcn +```json Request -wcn { "commands": [ { "command": "fill", "target": "e2", "value": "ada@example.com" }, @@ -236,7 +236,7 @@ Text matches a case-insensitive substring unless you set `exact: true`. When a l A failed command still returns `200`. Its error is in `results`, and the execution state is `failed`. Here a cookie banner covers the button: -```json !! Response -wcn +```json Response -wcn { "execution": { "id": "x-4", "state": "failed", "effect": "none", "replayed": false, "ran": 1 }, "results": [ @@ -257,7 +257,7 @@ A failed command still returns `200`. Its error is in `results`, and the executi Every response has a `next` value. Send it as `after` in your next request. A retried request with the same `after` and commands then runs only once. If another Commands API client changed the session in between, the response sets `epochChanged: true`. -```typescript !! Typescript -wcn +```typescript Typescript -wcn let after: string | undefined; async function step(commands: object[]) { @@ -274,7 +274,7 @@ async function step(commands: object[]) { Send a random `Idempotency-Key` header with each request, and reuse it when you retry that request. A retry with the same key returns the stored result with `replayed: true` instead of running the commands again. -```bash !! curl -wcn +```bash curl -wcn curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \ -H "steel-api-key: $STEEL_API_KEY" \ -H "Content-Type: application/json" \ @@ -295,7 +295,7 @@ Steel keeps results for at least an hour. Large parts, such as snapshot text and Executions run one at a time per session. The response waits up to 20 seconds. If the execution is still going, the response shows `state: "running"`. Wait for it with `status`, or stop it with `cancel`. -```json !! Request -wcn +```json Request -wcn { "commands": [{ "command": "status", "execution": "x-1" }] } ``` @@ -305,7 +305,7 @@ Executions run one at a time per session. The response waits up to 20 seconds. I Steel never answers a dialog on its own. An open dialog shows up in `dialog`, and commands on its tab fail with `dialog_pending` until you answer it. -```json !! Response -wcn +```json Response -wcn { "dialog": { "id": "d-1", "tab": "t1", "type": "confirm", "message": "Delete this item?" } } @@ -313,7 +313,7 @@ Steel never answers a dialog on its own. An open dialog shows up in `dialog`, an Answer it with the `dialog` command. Pass `text` to answer a prompt. -```json !! Request -wcn +```json Request -wcn { "commands": [{ "command": "dialog", "dialog": "d-1", "action": "accept" }] } ``` @@ -321,13 +321,13 @@ Answer it with the `dialog` command. Pass `text` to answer a prompt. `upload` takes files from the session's files, so upload them first with the [Files API](/overview/files-api/overview). Then pass their names. -```json !! Request -wcn +```json Request -wcn { "commands": [{ "command": "upload", "target": { "label": "Resume" }, "files": "resume.pdf" }] } ``` `wait` with `download: true` waits for the next download to finish. Its result has the file name and size. -```json !! Request -wcn +```json Request -wcn { "commands": [ { "command": "click", "target": { "role": "button", "name": "Export CSV" } }, @@ -338,7 +338,7 @@ Answer it with the `dialog` command. Pass `text` to answer a prompt. Then download the file from the session's files: -```bash !! curl -wcn +```bash curl -wcn curl https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \ -H "steel-api-key: $STEEL_API_KEY" \ -o report.csv diff --git a/content/docs/overview/commands-api/reference.mdx b/content/docs/overview/commands-api/reference.mdx index 9aada4e4..9ca361a5 100644 --- a/content/docs/overview/commands-api/reference.mdx +++ b/content/docs/overview/commands-api/reference.mdx @@ -8,7 +8,7 @@ publishedAt: "2026-11-04" `POST /v1/sessions/{sessionId}/commands` runs commands in a live session. The full schema is also in the [API reference](/api-reference). -```bash !! curl -wcn +```bash curl -wcn curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \ -H "steel-api-key: $STEEL_API_KEY" \ -H "Content-Type: application/json" \ @@ -35,7 +35,7 @@ Fields that are not listed, or that a command does not take, fail with `400 inva ### Response -```json !! Response -wcn +```json Response -wcn { "next": "op_4f8k2m9q1x", "epoch": 3, @@ -122,7 +122,7 @@ Input commands that start a navigation wait up to 15 seconds for the new page's `wait` takes one of the conditions below, and an optional `timeout` in milliseconds. The default timeout is 10 seconds and the most is 50 seconds. -```json !! Request -wcn +```json Request -wcn { "commands": [{ "command": "wait", "target": { "text": "Order placed" }, "timeout": 20000 }] } ``` @@ -156,7 +156,7 @@ Input commands that start a navigation wait up to 15 seconds for the new page's Element commands take `target`: a ref such as `e12`, a CSS selector, or a locator object. A locator sets exactly one of `role`, `text`, `label`, `placeholder`, `alt`, `title`, `testid`, or `css`. -```json !! Request -wcn +```json Request -wcn { "commands": [ {