Browser MCP quickstart

Requirements

An MCP client such as Claude Desktop, Cursor, Codex, or your own MCP runner
For hosted Browser MCP: a StableBrowse API key from the settings page
For local Browser MCP: Node.js 20 or newer and a StableBrowse MCP checkout

Hosted Browser MCP

Hosted Browser MCP is the recommended setup for end users. The browser runs in StableBrowse cloud; your LLM app only needs the MCP endpoint and your StableBrowse API key.

Sign in to StableBrowse.
Open settings.
Create an API key.
Add the hosted Browser MCP endpoint to your MCP client:

http://Stable-Servi-xpbtj3YEoY3C-1719471673.us-west-2.elb.amazonaws.com/mcp

Send the API key as a bearer token.

The client should authenticate every MCP request with:

Authorization: Bearer sb_live_...

Your LLM key stays with your LLM app or model provider. The StableBrowse API key authenticates access to the hosted browser.

Local install

Hosted Browser MCP does not require a local browser process. If you want to run the MCP server yourself, use a source checkout:

npm install
npm run build

Run over stdio

Most desktop MCP clients use stdio:

node dist/index.js

Example MCP client config:

{
  "mcpServers": {
    "stablebrowse": {
      "command": "node",
      "args": ["/absolute/path/to/stablebrowse-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Then ask the client something like:

Open Hacker News and tell me the title, points, and comment count for the top 3 stories.

Run as an HTTP endpoint

For local integration tests:

node dist/index.js --transport http --host 127.0.0.1 --port 3000

Endpoints:

Endpoint	Purpose
`POST http://127.0.0.1:3000/mcp`	Streamable HTTP MCP endpoint
`GET http://127.0.0.1:3000/health`	Health check

For a hosted deployment that accepts dashboard-created StableBrowse API keys:

STABLEBROWSE_TRANSPORT=http \
STABLEBROWSE_HOST=0.0.0.0 \
STABLEBROWSE_AUTH_MODE=dynamodb \
STABLEBROWSE_API_KEY_TABLE=stablebrowse-api-keys \
node dist/index.js

Common options

Flag	Description	Default
`--transport <stdio\|http>`	MCP transport. `sse` is accepted as an alias for `http`.	`stdio`
`--knowledge-graph-dir <path>`	Override bundled knowledge graph index path.	`data/knowledgegraphindex`
`--auth-mode <none\|static\|dynamodb>`	Auth mode for HTTP `/mcp` requests.	`none`
`--api-key <key>`	Allowed bearer key for local `static` auth tests.	-
`--api-key-table <table>`	DynamoDB API-key table for hosted `dynamodb` auth.	`stablebrowse-api-keys`
`--auth-cache-ttl <ms>`	Time to cache DynamoDB auth lookups.	`60000`
`--host <host>`	Host for HTTP transport. Use `0.0.0.0` to expose on the network.	`127.0.0.1`
`--port <number>`	HTTP port.	`3000`
`--headless <true\|false>`	Run browser headless.	`true`
`--headed`	Shortcut for `--headless false`.	-
`--proxy <url>`	Default proxy URL. Supports HTTP, HTTPS, and SOCKS5.	-
`--fingerprint <seed>`	Default fingerprint seed.	random
`--humanize`	Enable human-like mouse and keyboard behavior by default.	`false`
`--human-preset <default\|careful>`	Humanization preset.	`default`
`--log-level <debug\|info\|warn\|error>`	Server log level.	`info`

Environment variables use the STABLEBROWSE_* prefix. For example:

STABLEBROWSE_KNOWLEDGE_GRAPH_DIR=/path/to/knowledgegraphindex
STABLEBROWSE_PROXY=http://user:pass@host:port
STABLEBROWSE_LOG_LEVEL=warn
STABLEBROWSE_AUTH_MODE=dynamodb
STABLEBROWSE_API_KEY_TABLE=stablebrowse-api-keys

First successful run

In a typical run the agent should:

call create_session
call navigate
call content.get_markdown, extract.page_summary, or snapshot
use click, fill, fill_form, or interact if action is needed
return the final answer

If an agent takes screenshots for ordinary text tasks, improve its system prompt. Screenshots are useful for visual verification, but text and structured extraction tools are cheaper and usually more reliable.

Troubleshooting

Symptom	What to check
No tools appear	Confirm the MCP command path points to `dist/index.js` and `npm run build` completed.
Hosted MCP returns 401	Confirm the request has `Authorization: Bearer sb_live_...` and the key has not been revoked.
Browser does not launch	Confirm Node 20+, StableBrowse browser runtime availability, and permissions for the runtime environment.
Site blocks or challenges	Try a proxy, persistent profile, or humanize mode. Some websites may still block automation.
Agent loops on snapshots	Encourage `extract`, `content.get_markdown`, and `knowledge` before broad snapshots.
Ref click fails	Take a fresh `snapshot`, use `snapshot` with `contains`/`roles`, or use `interact.find`.

Getting started

Concepts

SDKs

Browser MCP

Reference

Requirements

Hosted Browser MCP

Local install

Run over stdio

Run as an HTTP endpoint

Common options

First successful run

Troubleshooting

​Requirements

​Hosted Browser MCP

​Local install

​Run over stdio

​Run as an HTTP endpoint

​Common options

​First successful run

​Troubleshooting

Requirements

Hosted Browser MCP

Local install

Run over stdio

Run as an HTTP endpoint

Common options

First successful run

Troubleshooting