Steel MCP Server

https://github.com/steel-dev/steel-mcp-server
Admin
Steel MCP Server provides a Model Context Protocol (MCP) server for Steel cloud browsers, enabling...
Tokens:169,163
Snippets:1,111
Trust Score:8.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Usage example for startHostedServer

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/hosted.md

Shows how to start the hosted server with the process environment, log the listening port, and gracefully shut down on SIGTERM.

```typescript
import { startHostedServer } from 'steel-mcp/hosted';

const server = await startHostedServer({ env: process.env });
console.log(`listening on :${server.port}/mcp`);

process.on('SIGTERM', () => void server.close().then(() => process.exit(0)));
```

--------------------------------

### Install hosted dependencies with npm

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/docs/HOSTING.md

Install the two required packages for the hosted entrypoint, plus optional OTLP tracing packages. These are declared as optional peerDependencies, so a default install omits them.

```bash
npm install ioredis @modelcontextprotocol/node
# and, only if you want OTLP tracing:
npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
```

--------------------------------

### Start tracing with startTracing and shutdown

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/telemetry.md

Shows how to start tracing with `startTracing`, passing `process.env` and an `onWarn` callback that logs warnings. After serving, call `shutdown()` to flush before the process exits. The imports from `steel-mcp` are for context propagation.

```ts
import { startTracing } from 'steel-mcp/tracing';
import { resolveTracer, activeTraceparent, contextFromRequestMeta } from 'steel-mcp';

const tracing = await startTracing(process.env, { onWarn: m => console.warn(m) });
// ... serve ...
await tracing?.shutdown(); // flush before the process exits
```

--------------------------------

### Usage examples for steel MCP tools

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/session.md

Example JSON-RPC invocations for the steel MCP tools, including steel_session_live_view with action 'acquire'.

```json
{ "name": "steel_session_create", "arguments": { "timeout_ms": 300000 } }
{ "name": "steel_navigate", "arguments": { "session_id": "sess_x", "url": "https://example.com" } }
{ "name": "steel_session_release", "arguments": { "session_id": "sess_x" } }
{ "name": "steel_session_diagnostics", "arguments": { "steel_session_id": "3f7c90e9-...." } }
{ "name": "steel_session_live_view", "arguments": { "action": "acquire", "session_id": "sess_x", "control_token": "..." } }
```

--------------------------------

### Unpack and compare the candidate with the installed steel-mcp

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/005-lifecycle-efficient-shopping-workflow.md

Unpacks the exact candidate .mcpb into a temporary directory and uses diff -qr to compare it with the installed runtime at claude_steel_install. This ensures the installed version matches the packed payload.

```bash
candidate_version="$(node -p 'require("./package.json").version')"
candidate_unpack="$(mktemp -d)"
npx --yes @anthropic-ai/mcpb@2.1.2 unpack "build/steel-mcp-$candidate_version.mcpb" "$candidate_unpack"
diff -qr "$candidate_unpack" "$claude_steel_install"
```

--------------------------------

### steel_wait_for usage example

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/browse.md

Example sequence of tool calls ending with steel_wait_for. Shows how to navigate, snapshot, find, act, and finally wait for text with a 30-second timeout.

```json
{ "name": "steel_navigate", "arguments": { "session_id": "sess_x", "url": "https://example.com" } }
{ "name": "steel_snapshot", "arguments": { "session_id": "sess_x" } }
{ "name": "steel_find", "arguments": { "session_id": "sess_x", "text": "checkout" } }
{ "name": "steel_act", "arguments": { "session_id": "sess_x", "action": "click", "target": "@e3" } }
{ "name": "steel_act", "arguments": { "session_id": "sess_x", "action": "fill_form", "fields": [ { "target": "@e1", "value": "Ada" } ] } }
{ "name": "steel_wait_for", "arguments": { "session_id": "sess_x", "text": "Order confirmed", "timeout_ms": 30000 } }
```

--------------------------------

### Error handling example for startHostedServer

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/hosted.md

Shows how to catch startup errors, such as missing STEEL_ALLOWED_HOSTS, and exit with a failure message.

```typescript
try {
    await startHostedServer({ env: {} }); // no STEEL_ALLOWED_HOSTS
} catch (error) {
    console.error('refusing to start:', error instanceof Error ? error.message : error);
    process.exit(1);
}
```

--------------------------------

### Usage example for createSessionPlanCodec and recommendSession

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/session-plan.md

Shows how to create the codec and generate a recipe for an account goal with persist_profile and long_running needs. The recipe recommends steel_session_create and the minted token is passed as configuration to steel_session_create.

```typescript
import { createSessionPlanCodec, recommendSession } from './src/core/session-plan.js';

const codec = createSessionPlanCodec(config.requestStateSecret, principal);
const recipe = recommendSession({
    origin: 'https://example.com',
    goal: 'account',
    needs: ['persist_profile', 'long_running'],
    minutes: 30,
    configuredTimeoutMs: 900_000,
    accountMaxMs: 3_600_000,
});
console.log(recipe.recommendedTool); // 'steel_session_create'

const token = await codec.mint(recipe.state, ctx); // pass as `configuration` to steel_session_create
```

--------------------------------

### Usage example with HostedRuntime

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/hosted-runtime.md

Shows how to create a backend with createHandleRegistryBackend and pass it to HostedRuntime. Requires onError when REDIS_URL is set to handle Redis client errors.

```typescript
import { HostedRuntime, createHandleRegistryBackend } from 'steel-mcp/hosted-runtime';
import { loadConfig } from 'steel-mcp';

const backend = createHandleRegistryBackend({ env: process.env, onError: e => log('error', String(e)) });
const runtime = new HostedRuntime({
    configForCredential: credential => ({ ...template, apiKey: credential }),
    createRegistry: backend.createRegistry,
    onReleased: (cause, backend) => log('info', 'released', { cause, backend }),
});
```

--------------------------------

### Usage example with paginate and successResult

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/envelope.md

Shows how to paginate snapshot text and build a successful tool result with envelope sections. Uses DEFAULT_MAX_TOKENS and the cursor from arguments, and includes a pagination hint when truncated.

```ts
import { successResult, describeChange } from './src/core/envelope.js';
import { paginate, DEFAULT_MAX_TOKENS } from './src/core/pagination.js';

const page = paginate(snapshotText, { maxTokens: DEFAULT_MAX_TOKENS, cursor: args.cursor });
return successResult(
    {
        result: 'Read the page.',
        snapshot: page.text,
        pagination: page.truncated ? `Continue with cursor="${page.nextCursor}".` : undefined,
    },
    { snapshot_id: 's3' }
);
```

--------------------------------

### Pack and open the exact candidate (npm run pack:mcpb, open)

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/005-lifecycle-efficient-shopping-workflow.md

Packs the MCP server into an .mcpb file and opens it to install in Claude Desktop. The version is read dynamically from package.json.

```bash
npm run pack:mcpb
open "build/steel-mcp-$(node -p 'require("./package.json").version').mcpb"
```

--------------------------------

### startHostedServer(options: HostedServerOptions): Promise<HostedServer>

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/hosted.md

Starts the hosted server. Every caller authenticates to Steel with their own key, so the configuration is built per credential rather than once. Returns a HostedServer object with port and close method.

```APIDOC
## startHostedServer(options: HostedServerOptions): Promise<HostedServer>

### Description
Starts the hosted server. Every caller authenticates to Steel with their own key, so the configuration is built per credential rather than once. Returns a HostedServer object with port and close method.

### Method
startHostedServer

### Endpoint
N/A (SDK function)

### Parameters
#### Options
- **env** (Record<string, string | undefined>) - Required - The process environment
- **runtime** (Pick<HostedRuntimeOptions, 'createApi' | 'createPool' | 'createLimiter' | 'now'>) - Optional - Test seams for the Steel clients a request gets
- **log** (Log) - Optional - Log sink (default: structured JSON to stdout)

### Request Example
```ts
import { startHostedServer } from 'steel-mcp/hosted';

const server = await startHostedServer({ env: process.env });
console.log(`listening on :${server.port}/mcp`);

process.on('SIGTERM', () => void server.close().then(() => process.exit(0)));
```

### Response
#### Success Response
- **port** (number) - The bound port, which is the assigned one when `PORT` is 0
- **close** (function) - Stops accepting, then releases every session this replica still holds

#### Response Example
```ts
{
  port: 8080,
  close: async () => {}
}
```

### Error Handling
All startup failures throw `Error` synchronously. Examples:
- `STEEL_ALLOWED_HOSTS` is required; empty throws ("An empty allowlist would reject every request").
- `STEEL_ALLOWED_ORIGINS` parse only; absent means no browser Origin is allowed.
- `PORT` parsed (default 8080, `0` asks the OS for a free port, 1–65535); `HOST` defaults to `0.0.0.0`.
- `loadConfig` validates profile/timeouts/base URL once; requires `deployment === 'cloud'`.
- `startTracing(env)` is called before the runtime.
- `createHandleRegistryBackend` picks memory vs Redis.

### Environment Variables
All stdio variables (`STEEL_BASE_URL`, `STEEL_PROFILE`, `STEEL_SESSION_TIMEOUT_MS`, `STEEL_INACTIVITY_TIMEOUT_MS`, `STEEL_MAX_SESSIONS`, `STEEL_REQUEST_STATE_SECRET`) **except** `STEEL_API_KEY`, plus `STEEL_ALLOWED_HOSTS`, `STEEL_ALLOWED_ORIGINS`, `PORT`, `HOST`, `REDIS_URL`, `REDIS_KEY_PREFIX`, `OTEL_*`.
```

--------------------------------

### Add steel_session_options instruction

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/007-add-budgeted-session-options.md

Instruction to add to the agent prompt for non-default setup. Must be concise and fit within the 2,000-byte target (2,048 hard) while retaining all existing requirements.

```text
For non-default setup, call steel_session_options with the target URL and
explicit needs, then pass its signed configuration to steel_session_create.
```

--------------------------------

### steel_session_live_view

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/session.md

Documentation for the steel_session_live_view tool, including its parameters, schema, behavior, usage example, and error handling.

```APIDOC
## `registerSessionLiveView(host, deps): void` — tool `steel_session_live_view`

### Description
App-only viewer and control lease; no page content. `_meta.ui.visibility: ['app']` keeps it out of the model-visible list. Annotations: `destructiveHint`, `openWorldHint`.

### Tool Name
`steel_session_live_view`

### Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| session_id | `string` | newest live | Which session |
| action | `'connect' \| 'acquire' \| 'renew' \| 'release'` | `'connect'` | Lease operation |
| control_token | `string` | — | Required for `renew`/`release` |

### Schema (strict)
```ts
z.object({
    session_id: sessionIdSchema.optional()
        .describe('Omit to stream the newest live session this credential owns, which is what a viewer that never received the session does.'),
    action: z.enum(['connect', 'acquire', 'renew', 'release']).optional(),
    control_token: z.string().optional(),
}).strict()
```

### Behavior
- `connect`: resolves the record (named or newest live — `session_expired` if none), reads `getSession` fresh (the websocket token is re-minted per read), and returns `{ session_id (handle), cdp_url, viewport?, expires_at }` — deliberately nothing else, since the CDP URL is a drive-capable credential.
- `acquire`/`renew`/`release`: manage the human-control lease (`HUMAN_CONTROL_LEASE_MS = 60_000`) via the registry; `acquire`/`renew` return `control: { state: 'human', token, lease_expires_at }`, `release` returns `control: { state: 'agent' }`.

### Usage Example
```json
{ "name": "steel_session_live_view", "arguments": { "action": "acquire", "session_id": "sess_x", "control_token": "..." } }
```

### Errors
`invalid_argument` (option conflicts, bad guest/profile/namespace, lease misuse), `self_host_unsupported`, `rate_limited` (session cap), `session_expired`, `not_found`, `human_control_active`, `timeout` (cancelled create). See [errors.md](../../errors.md).
```

--------------------------------

### Usage example for InMemoryRateLimiter

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/rate-limit.md

Shows how to instantiate the limiter and charge a principal for a tool call. Catches rate_limited errors and logs retry-after seconds and details.

```typescript
import { InMemoryRateLimiter, DEFAULT_RATE_LIMIT_POLICY } from 'steel-mcp';

const limiter = new InMemoryRateLimiter({ policy: { refillPerMinute: 20, burstCapacity: 40 } });

try {
    await limiter.charge('a1b2c3...', 'steel_session_create');
    // admitted
} catch (error) {
    if (error instanceof SteelToolError && error.code === 'rate_limited') {
        console.error(error.retryAfterSeconds); // seconds to wait
        console.error(error.details);          // tool, cost, availableUnits, ...
    }
}
```

--------------------------------

### Usage example with withPage and successResult

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/shared.md

Shows how to use `withPage` to navigate a page and return a success result with metadata. Errors thrown inside `work` become tool-execution error results.

```typescript
import { guard, withPage, fencedSection, successResult, sessionIdSchema } from './src/core/tools/shared.js';

return withPage(deps, 'steel_navigate', ctx.mcpReq, args.session_id, async (page, record) => {
    const outcome = await page.navigate(args.url);
    return successResult({ result: `Opened ${args.url}.`, change: outcome.changeDescription }, {
        final_url: outcome.finalUrl, navigated: outcome.change.navigated,
    });
});
```

--------------------------------

### Find the Claude extension root and installed steel-mcp directory

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/005-lifecycle-efficient-shopping-workflow.md

Determines the Claude Desktop extensions root directory and searches for the installed steel-mcp installation. Expect exactly one result and assign its absolute path to claude_steel_install; never commit that path.

```bash
claude_extensions_root="$(node -p 'require("node:path").join(require("node:os").homedir(), "Library/Application Support/Claude/Claude Extensions")')"
find "$claude_extensions_root" -maxdepth 1 -type d -name 'local.mcpb.*steel*' -print
```

--------------------------------

### Steel MCP tool usage examples

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/interactive.md

Example JSON payloads for the Steel MCP tools: steel_session_handoff, steel_batch, steel_session_replay, and steel_session_options. Each object shows the tool name and its arguments, such as session_id, reason, steps, steel_session_id, url, goal, and needs. These are used to invoke the respective tools via the MCP protocol.

```json
{ "name": "steel_session_handoff", "arguments": { "session_id": "sess_x", "reason": "sensitive_input" } }
{ "name": "steel_batch", "arguments": { "session_id": "sess_x", "steps": [ { "tool": "steel_navigate", "arguments": { "url": "https://shop.example" } }, { "tool": "steel_act", "arguments": { "action": "click", "target": "@e2" } } ] } }
{ "name": "steel_session_replay", "arguments": { "steel_session_id": "3f7c90e9-...." } }
{ "name": "steel_session_options", "arguments": { "url": "https://shop.example/login", "goal": "account", "needs": ["persist_profile"] } }
```

--------------------------------

### Page navigation, screenshot, snapshot, and action usage

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/page.md

Shows how to get a page from the pool, navigate to a URL, capture a screenshot, take a snapshot, filter clickable nodes, and perform a click action.

```typescript
const page = await deps.pool.page(sessionHandle);
const outcome = await page.navigate('https://example.com');
console.log(outcome.finalUrl, outcome.changeDescription);

const shot = await page.captureScreenshot({ fullPage: false });

const snapshot = await page.snapshot({});
const clickable = snapshot.nodes.filter(n => n.ref);
await page.act({ action: 'click', target: clickable[0]?.ref });
```

--------------------------------

### Fence format example

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/untrusted.md

Shows the structure of the fence that wraps untrusted content, including the provenance header and the notice.

```plaintext
<untrusted-page-content source="..." fetched-at="...">
The text below ... (UNTRUSTED_CONTENT_NOTICE)

<content>
</untrusted-page-content>
```

--------------------------------

### Usage example for createSteelHttpHandler

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/http.md

Shows how to create the hosted HTTP handler with allowed hostnames, origin hostnames, and a depsForRequest callback. The handler.fetch can be served from any web-standard runtime; Node uses toNodeHandler(handler).

```typescript
import { createSteelHttpHandler } from 'steel-mcp/http';

const handler = createSteelHttpHandler({
    allowedHostnames: ['mcp.example.com'],
    allowedOriginHostnames: ['app.example.com'],
    depsForRequest: async ({ credential, principal, request }) => runtime.depsForRequest({ credential, principal, request }),
    onerror: error => console.error(error),
});
// serve handler.fetch from any web-standard runtime; Node uses toNodeHandler(handler)
```

--------------------------------

### Using CdpConnection to attach to a page and evaluate JavaScript

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/cdp.md

Example of connecting to a Steel browser, attaching to a page, sending a CDP command, subscribing to an event, unsubscribing, and closing the connection.

```ts
import { CdpConnection } from './src/core/steel/cdp.js';

const connection = await CdpConnection.connect('wss://connect.steel.dev/?sessionId=...&apiKey=...', signal);
const session = await connection.attachToPage();
const { result } = await session.send('Runtime.evaluate', { expression: 'document.title', returnByValue: true });
const off = session.on('Page.loadEventFired', () => console.log('loaded'));
off(); // unsubscribe
await connection.close();

```

--------------------------------

### steel_session_options request for account goal

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/docs/SESSIONS.md

Example of the steel_session_options request body for a non-default session with an account goal, persistence and location needs, and a country filter. The returned configuration token expires after ten minutes.

```json
{
  "url": "https://example.com/account",
  "goal": "account",
  "needs": ["persist_profile", "location"],
  "country": "DE"
}
```

--------------------------------

### Run development commands

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/README.md

Development commands for building, type-checking, linting, testing, and running the MCP conformance suite. The test:browser command runs the inline viewer and frame snapshot in a real Chrome, while test:e2e starts, waits for, and tears down the real-browser stack.

```bash
npm run build
npm run typecheck
npm run lint
npm test               # unit + integration
npm run budget         # tools/list byte budget per profile
npm run conformance    # MCP conformance suite
npm run test:browser   # runs the inline viewer and the frame snapshot in a real Chrome
npm run test:e2e       # starts, waits for and tears down the real-browser stack
```

--------------------------------

### Tool annotations for steel_session_options

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/007-add-budgeted-session-options.md

Tool annotations for the session options tool. It is read-only, idempotent, and open-world, and it does not start a browser or consume a concurrency slot. Set TOOL_COSTS.steel_session_options to 3 because account plus long-running planning may perform profile, credential, and account-details reads.

```ts
annotations: {
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: true,
}
```

--------------------------------

### MCP client usage examples

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/stateless.md

JSON payloads for invoking steel_scrape, steel_screenshot, and steel_pdf tools from an MCP client. The first block shows steel_scrape with format and max_tokens; the second block shows steel_screenshot with full_page or session_id, and steel_pdf with url and use_proxy.

```json
{ "name": "steel_scrape", "arguments": { "url": "https://example.com", "format": ["markdown"], "max_tokens": 8000 } }
```

```json
{ "name": "steel_screenshot", "arguments": { "url": "https://example.com", "full_page": true } }
{ "name": "steel_screenshot", "arguments": { "session_id": "sess_..." } }
{ "name": "steel_pdf", "arguments": { "url": "https://example.com/invoice", "use_proxy": true } }
```

--------------------------------

### Health check response JSON

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Example response body for the GET /healthz endpoint, returning status and version.

```json
{ "status": "ok", "version": "3.0.0" }
```

--------------------------------

### Catch SteelToolError in embedder code

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/errors.md

In-process embedder example for catching SteelToolError. Use `toolErrorResult(error)` to get the exact CallToolResult a client would see. The switch handles specific error codes: `stale_ref` (relocate with steel_find / steel_snapshot, retry once), `click_blocked` (hand off to a person if `details.handoff_required`), `rate_limited` (wait or switch to stateless reads), `bot_detection` (use `details.rung` mitigation), and `human_control_active`.

```ts
import { SteelToolError, toolErrorResult } from 'steel-mcp';

try {
    await page.act({ action: 'click', target: '@e3' });
} catch (error) {
    if (error instanceof SteelToolError) {
        switch (error.code) {
            case 'stale_ref':      // relocate with steel_find / steel_snapshot, retry once
            case 'click_blocked':  // error.details.handoff_required → hand the browser to a person
            case 'rate_limited':   // error.retryAfterSeconds → wait, or switch to stateless reads
            case 'bot_detection':  // error.details.rung → the one mitigation to try next
            case 'human_control_active':
                break;
        }
        const result = toolErrorResult(error); // the exact CallToolResult a client would see
    }
}
```

--------------------------------

### GET /v1/details

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/steel-rest.md

Gets account details via the Steel /v1/details endpoint.

```APIDOC
## GET /v1/details

### Description
Gets account details.

### Method
GET

### Endpoint
/v1/details

### Response
#### Success Response (200)
- **AccountDetails** - The account details.

### Errors
- `timeout` - Request cancelled by caller's signal.
- `steel_error` - Steel unreachable, empty body, or unmapped HTTP status.
- `unauthorized` (401), `forbidden` (403), `payment_required` (402), `not_found` (404), `proxy_failure` (407), `rate_limited` (429) - Mapped HTTP errors.
```

--------------------------------

### GET /v1/profiles/{id}

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/steel-rest.md

Gets a browser profile by ID via the Steel /v1/profiles/{id} endpoint.

```APIDOC
## GET /v1/profiles/{id}

### Description
Gets a browser profile by ID.

### Method
GET

### Endpoint
/v1/profiles/{id}

### Parameters
#### Path Parameters
- **profileId** (string) - Required - The ID of the profile to retrieve.

### Response
#### Success Response (200)
- **SteelProfileSummary** - The profile summary.

### Errors
- `timeout` - Request cancelled by caller's signal.
- `steel_error` - Steel unreachable, empty body, or unmapped HTTP status.
- `unauthorized` (401), `forbidden` (403), `payment_required` (402), `not_found` (404), `proxy_failure` (407), `rate_limited` (429) - Mapped HTTP errors.
```

--------------------------------

### GET /v1/sessions/{id}

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/steel-rest.md

Gets a browser session by ID via the Steel /v1/sessions/{id} endpoint.

```APIDOC
## GET /v1/sessions/{id}

### Description
Gets a browser session by ID.

### Method
GET

### Endpoint
/v1/sessions/{id}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to retrieve.

### Response
#### Success Response (200)
- **SteelSession** - The session details.

### Errors
- `timeout` - Request cancelled by caller's signal.
- `steel_error` - Steel unreachable, empty body, or unmapped HTTP status.
- `unauthorized` (401), `forbidden` (403), `payment_required` (402), `not_found` (404), `proxy_failure` (407), `rate_limited` (429) - Mapped HTTP errors.
```

--------------------------------

### GET /v1/sessions/{id}/hls

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/steel-rest.md

Gets the HLS stream for a session via the Steel /v1/sessions/{id}/hls endpoint.

```APIDOC
## GET /v1/sessions/{id}/hls

### Description
Gets the HLS stream for a session. Accepts `application/vnd.apple.mpegurl` and validates the `#EXTM3U` header.

### Method
GET

### Endpoint
/v1/sessions/{id}/hls

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **string** - The HLS stream content.

### Errors
- `timeout` - Request cancelled by caller's signal.
- `steel_error` - Steel unreachable, empty body, or unmapped HTTP status.
- `unauthorized` (401), `forbidden` (403), `payment_required` (402), `not_found` (404), `proxy_failure` (407), `rate_limited` (429) - Mapped HTTP errors.
```

--------------------------------

### Verify session-plan and pagination tests

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/007-add-budgeted-session-options.md

Run the unit tests for the session-plan codec and pagination. Expected: the pure matrix and pagination pass before registration.

```sh
npx vitest run --project unit tests/unit/session-plan.test.ts tests/unit/pagination.test.ts
```

--------------------------------

### Usage: constructing ServerDeps and creating the server

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/server.md

Shows the stdlib pattern for building ServerDeps and calling createSteelMcpServer. The resulting server is then handed to a transport.

```typescript
import { loadConfig, CdpSessionPool, InMemoryHandleRegistry, createHandoffCodec,
         createSessionPlanCodec, principalFromCredential, SteelRestClient,
         createSteelMcpServer } from 'steel-mcp';

const config = loadConfig(process.env);
const api = new SteelRestClient(config);
const pool = new CdpSessionPool(config, 2);
const registry = new InMemoryHandleRegistry({
    releaseSteelSession: async (id, principal) => { await pool.close(id); await api.releaseSession(id); },
});
const principal = principalFromCredential(config.apiKey ?? 'self-hosted');
const deps = {
    config, api, pool, registry,
    handoffState: createHandoffCodec(config.requestStateSecret),
    sessionPlanState: createSessionPlanCodec(config.requestStateSecret, principal),
    principal,
    settleMultiplier: config.deployment === 'cloud' ? 2 : 1,
    now: () => new Date(),
};
const server = createSteelMcpServer(deps); // McpServer from @modelcontextprotocol/server

```

--------------------------------

### toolErrorResult structuredContent example

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/errors.md

Example of the structuredContent produced by toolErrorResult for any throwable. The error object includes the stable code, message, optional documentation link, retry-after seconds, and details. Non-SteelToolError throwables receive code 'steel_error' and their message.

```json
{ "error": { "code": "...", "message": "...", "linkToDocs": "...", "retryAfterSeconds": 5, "details": { ... } } }
```

--------------------------------

### Recommended Semantic Shape for SERVER_INSTRUCTIONS Copy

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/005-lifecycle-efficient-shopping-workflow.md

Recommended compact wording for the server instructions copy in Step 2. Specifies when to create and preserve a single interactive session, how to handle batch operations and handoffs, and to stop before payment/final confirmation.

```text
Use scrape while it supplies the evidence. At the first necessary stateful interaction,
create one session sized for the remaining active task and handoff; preserve it through
comparison and cart. expires_at cannot extend and replacements do not inherit page/cart.

Batch the next few known reversible steps only when later targets need no read. At a
detected login/challenge boundary, hand off on the same session and resume with only
unrun steps. Stop before payment/final confirmation even when no detector fires.
```

--------------------------------

### GET /v1/credentials

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Lists credentials filtered by exact origin and namespace.

```APIDOC
## GET /v1/credentials

### Description
Lists credentials filtered by exact origin and namespace.

### Method
GET

### Endpoint
/v1/credentials

### Parameters
#### Query Parameters
- **origin** (string) - Optional - Filter by origin.
- **namespace** (string) - Optional - Filter by namespace.

### Response
#### Success Response (200)
- **credentials** (array) - List of SteelCredentialSummary objects.

```

--------------------------------

### Package structure

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/PLAN.md

Directory tree showing the repository layout with core modules, HTTP boundary, and entrypoints.

```text
src/
  core/
    tools/           # scrape, screenshot, pdf, session, navigate, snapshot, find, act, wait, diagnostics, batch
    profiles.ts      # scrape | browse | vision | full
    snapshot.ts      # a11y tree, @eN refs keyed on (loaderId, backendNodeId), versioned
    settle.ts        # WaitForHelper: frame-navigation + MutationObserver quiescence
    untrusted.ts     # provenance fencing, invisible-content stripping, password redaction
    registry.ts      # handle registry + reaper
    steel/           # typed REST layer over /v1 + CDP client
    errors.ts        # Steel failure -> actionable tool-execution error
    apps/            # the MCP-App session viewer shell (§14.A)
  http.ts            # Streamable HTTP boundary: routing, DNS-rebinding guards, credentials
  hosted-runtime.ts  # shared per-credential clients, handle store selection
  hosted.ts          # hosted entrypoint: binds a port, serves /mcp and /healthz
  stdio.ts           # stdio entrypoint (bin: steel-mcp)
```

--------------------------------

### GET /v1/sessions

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Lists browser sessions with optional filtering and pagination.

```APIDOC
## GET /v1/sessions

### Description
Lists browser sessions with optional filtering and pagination.

### Method
GET

### Endpoint
/v1/sessions

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by session status.
- **limit** (number) - Optional - Maximum number of sessions to return.
- **cursorId** (string) - Optional - Pagination cursor.

### Response
#### Success Response (200)
- **sessions** (array) - List of sessions.
- **nextCursor** (string) - Cursor for the next page.
- **totalCount** (number) - Total number of sessions.

```

--------------------------------

### GET /v1/profiles

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/steel-rest.md

Lists browser profiles via the Steel /v1/profiles endpoint.

```APIDOC
## GET /v1/profiles

### Description
Lists browser profiles. Projects each item; invalid items are dropped, non-array answers throw.

### Method
GET

### Endpoint
/v1/profiles

### Response
#### Success Response (200)
- **SteelProfileSummary[]** - The list of profile summaries.

### Errors
- `timeout` - Request cancelled by caller's signal.
- `steel_error` - Steel unreachable, empty body, or unmapped HTTP status.
- `unauthorized` (401), `forbidden` (403), `payment_required` (402), `not_found` (404), `proxy_failure` (407), `rate_limited` (429) - Mapped HTTP errors.
```

--------------------------------

### GET /v1/sessions

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/steel-rest.md

Lists browser sessions via the Steel /v1/sessions endpoint.

```APIDOC
## GET /v1/sessions

### Description
Lists browser sessions.

### Method
GET

### Endpoint
/v1/sessions

### Parameters
#### Query Parameters
- **request** (SessionListRequest) - Required - The session list request payload.

### Response
#### Success Response (200)
- **SessionListResponse** - The list of sessions.

### Errors
- `timeout` - Request cancelled by caller's signal.
- `steel_error` - Steel unreachable, empty body, or unmapped HTTP status.
- `unauthorized` (401), `forbidden` (403), `payment_required` (402), `not_found` (404), `proxy_failure` (407), `rate_limited` (429) - Mapped HTTP errors.
```

--------------------------------

### Run complete verification suite

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/007-add-budgeted-session-options.md

Runs the complete verification suite. Expected that every command exits 0 and self-host E2E does not attempt cloud account reads/persistence.

```sh
npm run typecheck
npm run lint
npm test
npm run budget
npm run build
npm run conformance
npm run pack:mcpb
npm run test:browser
npm run test:e2e
```

--------------------------------

### PageState.lastSnapshot

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/snapshot.md

Gets the most recent snapshot for the page, or undefined if the page has never been read.

```APIDOC
## PageState.lastSnapshot

### Description
Gets the most recent snapshot for the page, or undefined if the page has never been read.

### Property
- **lastSnapshot** (PageSnapshot | undefined) - The most recent snapshot, or `undefined` if the page has never been read.
```

--------------------------------

### Load config and build CDP URL

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/config.md

Shows how to load configuration and build a CDP URL. Requires STEEL_API_KEY environment variable. The buildCdpUrl call returns a WebSocket URL like wss://connect.steel.dev/?apiKey=...&sessionId=...

```ts
import { loadConfig, buildCdpUrl, resolveInactivityTimeout } from 'steel-mcp';

const config = loadConfig({ STEEL_API_KEY: process.env.STEEL_API_KEY });
console.log(config.deployment, config.profile, config.maxConcurrentSessions);

const url = buildCdpUrl(config, '3f7c90e9-....'); // wss://connect.steel.dev/?apiKey=...&sessionId=...
```

--------------------------------

### Verify documentation and manifest updates

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/plans/007-add-budgeted-session-options.md

Runs integration, unit, and budget checks after updating documentation and manifest. Expected to keep instructions within the 2,000-byte target, browse under 17,000, and pass all security/handoff assertions.

```sh
npx vitest run --project integration tests/integration/tools.test.ts
npx vitest run --project unit tests/unit/mcpb-manifest.test.ts
npm run budget
```

--------------------------------

### GET /v1/profiles/{id}

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Retrieves a browser profile by ID. Invalid metadata throws.

```APIDOC
## GET /v1/profiles/{id}

### Description
Retrieves a browser profile by ID. Invalid metadata throws.

### Method
GET

### Endpoint
/v1/profiles/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The profile ID.

### Response
#### Success Response (200)
- **SteelProfileSummary** (object) - The profile summary.

```

--------------------------------

### GET /v1/profiles

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Lists browser profiles. Returns a strict projection; non-array response throws.

```APIDOC
## GET /v1/profiles

### Description
Lists browser profiles. Returns a strict projection; non-array response throws.

### Method
GET

### Endpoint
/v1/profiles

### Response
#### Success Response (200)
- **profiles** (array) - List of SteelProfileSummary objects.

```

--------------------------------

### GET /v1/details

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Retrieves account details such as max session duration, concurrency limit, and plan.

```APIDOC
## GET /v1/details

### Description
Retrieves account details such as max session duration, concurrency limit, and plan.

### Method
GET

### Endpoint
/v1/details

### Response
#### Success Response (200)
- **maxSessionDuration** (number) - Maximum session duration.
- **concurrencyLimit** (number) - Concurrency limit.
- **plan** (string) - Plan name.

```

--------------------------------

### GET /v1/sessions/{id}/logs

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Retrieves logs for a session. Events are normalised to an empty array if missing.

```APIDOC
## GET /v1/sessions/{id}/logs

### Description
Retrieves logs for a session. Events are normalised to an empty array if missing.

### Method
GET

### Endpoint
/v1/sessions/{id}/logs

### Parameters
#### Path Parameters
- **id** (string) - Required - The session ID.

### Response
#### Success Response (200)
- **events** (array) - List of events.
- **total** (number) - Optional - Total count.
- **hasMore** (boolean) - Optional - Whether more events are available.

```

--------------------------------

### Sync version files from package.json

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/RELEASING.md

Use npm run sync:version to write the other version surfaces from package.json. The --check flag fails if any disagree and is what CI runs.

```bash
npm run sync:version            # write the other three from package.json
npm run sync:version -- --check # fail if any disagree; this is what CI runs
```

--------------------------------

### Cut a release: run checks, bump version, merge

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/RELEASING.md

Run all automated gates on a clean tree, bump the version with npm version, then merge the reviewed commit to main and dispatch release.yml for that SHA.

```bash
# 1. On a clean tree, with the checks passing.
npm run typecheck && npm run lint && npm test && npm run budget && npm run conformance

# 2. Bump on a normal reviewed branch. This rewrites the other version surfaces.
npm version --no-git-tag-version patch     # or minor / major / 2.1.0

# 3. Merge the reviewed commit to main, then manually dispatch release.yml for that exact SHA.
```

--------------------------------

### GET /v1/sessions/{id}/hls

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Retrieves the HLS stream (m3u8) for a session. Validates the #EXTM3U header.

```APIDOC
## GET /v1/sessions/{id}/hls

### Description
Retrieves the HLS stream (m3u8) for a session. Validates the #EXTM3U header.

### Method
GET

### Endpoint
/v1/sessions/{id}/hls

### Parameters
#### Path Parameters
- **id** (string) - Required - The session ID.

### Response
#### Success Response (200)
- **body** (string) - m3u8 text (Content-Type: application/vnd.apple.mpegurl).

```

--------------------------------

### GET /v1/sessions/{id}

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Retrieves a browser session by ID. Re-mints the websocketUrl token on every read.

```APIDOC
## GET /v1/sessions/{id}

### Description
Retrieves a browser session by ID. Re-mints the websocketUrl token on every read.

### Method
GET

### Endpoint
/v1/sessions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The session ID.

### Response
#### Success Response (200)
- **SteelSession** (object) - The session object.

```

--------------------------------

### steel_screenshot

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/stateless.md

Takes a screenshot of a page or an existing session. Usage examples provided from the MCP client perspective.

```APIDOC
## steel_screenshot

### Description
Takes a screenshot of a page or an existing session. Usage examples provided from the MCP client perspective.

### Method
MCP Tool Call

### Endpoint
`steel_screenshot`

### Parameters
#### Input Schema (inferred from examples)
- **url** (string) - Optional - The page to screenshot (if not using a session).
- **full_page** (boolean) - Optional - Whether to capture the full page.
- **session_id** (string) - Optional - The session ID to screenshot.

### Request Example
```json
{ "name": "steel_screenshot", "arguments": { "url": "https://example.com", "full_page": true } }
```

```json
{ "name": "steel_screenshot", "arguments": { "session_id": "sess_..." } }
```

### Response
Tool-execution error results may include `structuredContent.error.code` with values: `bot_detection`, `payment_required`, `rate_limited`, `unauthorized`, `steel_error`.

```

--------------------------------

### Claude Desktop config for Steel MCP server

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/docs/HOSTING.md

Configures Claude Desktop to connect to the Steel MCP server via a local bridge (mcp-remote). The header intentionally has no space after the colon and the credential is placed in env to avoid mangling by hosts that don't escape spaces in args. Prefer a header over the ?apiKey= query parameter.

```json
{
  "mcpServers": {
    "steel": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "https://mcp.example.com/mcp",
        "--header",
        "Authorization:${STEEL_AUTH_HEADER}"
      ],
      "env": { "STEEL_AUTH_HEADER": "Bearer <your-steel-api-key>" }
    }
  }
}
```

--------------------------------

### steel_scrape

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/tools/stateless.md

Scrapes a web page and returns its content. Usage example provided from the MCP client perspective.

```APIDOC
## steel_scrape

### Description
Scrapes a web page and returns its content. Usage example provided from the MCP client perspective.

### Method
MCP Tool Call

### Endpoint
`steel_scrape`

### Parameters
#### Input Schema (inferred from example)
- **url** (string) - Required - The page to scrape.
- **format** (array of strings) - Optional - Desired output formats (e.g., `["markdown"]`).
- **max_tokens** (number) - Optional - Maximum tokens for the response.

### Request Example
```json
{ "name": "steel_scrape", "arguments": { "url": "https://example.com", "format": ["markdown"], "max_tokens": 8000 } }
```

### Response
Tool-execution error results may include `structuredContent.error.code` with values: `bot_detection`, `payment_required`, `rate_limited`, `unauthorized`, `steel_error`.

```

--------------------------------

### Create SteelRestClient and scrape a page

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/steel-rest.md

Shows how to instantiate SteelRestClient with an API key and perform a scrape request, returning markdown content and link count.

```typescript
import { SteelRestClient, loadConfig } from 'steel-mcp';

const client = new SteelRestClient(loadConfig({ STEEL_API_KEY: 'key' }));
const page = await client.scrape({ url: 'https://example.com', format: ['markdown'] });
console.log(page.content.markdown, page.links.length);
```

--------------------------------

### Create CdpSessionPool and navigate a page

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/api-reference/context.md

Shows how to create a CdpSessionPool with a concurrency limit of 2, obtain a page for a session, navigate to a URL, and close the session. Requires a Steel REST client and handle registry, typically configured via loadConfig(process.env).

```ts
import { CdpSessionPool, loadConfig, SteelRestClient, InMemoryHandleRegistry } from 'steel-mcp';

const config = loadConfig(process.env);
const pool = new CdpSessionPool(config, 2);
const page = await pool.page('some-steel-session-id');
await page.navigate('https://example.com');
await pool.close('some-steel-session-id');
```

--------------------------------

### GET /v1/sessions/{id}/agent-traces

Source: https://github.com/steel-dev/steel-mcp-server/blob/main/_autodocs/endpoints.md

Retrieves agent traces for a session. Events are normalised to an empty array if missing.

```APIDOC
## GET /v1/sessions/{id}/agent-traces

### Description
Retrieves agent traces for a session. Events are normalised to an empty array if missing.

### Method
GET

### Endpoint
/v1/sessions/{id}/agent-traces

### Parameters
#### Path Parameters
- **id** (string) - Required - The session ID.

### Response
#### Success Response (200)
- **events** (array) - List of events.
- **total** (number) - Optional - Total count.
- **hasMore** (boolean) - Optional - Whether more events are available.

```
Tokens:
Raw