For AI agents: a documentation index is available at /llms.txt
Skip to main content

Browserless MCP in Factory Droid

Factory Droid connects to the hosted Browserless MCP server over Streamable HTTP, added with droid mcp add or an entry in ~/.factory/mcp.json. Once it's connected, Droid can scrape, search, crawl, and drive a cloud browser with the Browserless MCP tools.

Prerequisites

Connect to the hosted server​

The hosted server runs at https://mcp.browserless.io/mcp, so there's nothing to install.

Set BROWSERLESS_TOKEN in your environment, then run in your terminal:

droid mcp add browserless https://mcp.browserless.io/mcp --type http \
--header 'Authorization: Bearer ${BROWSERLESS_TOKEN}' --no-oauth

The single quotes keep the shell from expanding the variable, so Droid stores ${BROWSERLESS_TOKEN} and fills it in each time it connects. --no-oauth tells Droid the header handles authentication, so it doesn't start an OAuth sign-in. This writes the entry to ~/.factory/mcp.json. To edit the file by hand, or to share the server with your team in a project's .factory/mcp.json, add:

{
"mcpServers": {
"browserless": {
"type": "http",
"url": "https://mcp.browserless.io/mcp",
"headers": {
"Authorization": "Bearer ${BROWSERLESS_TOKEN}"
},
"oauth": false
}
}
}

Keep the ${BROWSERLESS_TOKEN} reference rather than a pasted token in a project file, since that file is usually committed. Droid only expands ${NAME} references in header values, not in url.

To sign in with OAuth instead, leave out --header and --no-oauth (or the headers block and "oauth": false). Then open /mcp in Droid and authenticate browserless, which opens a browser window to your Browserless account.

To use a region other than US West, add an x-browserless-api-url header, or a browserlessUrl query parameter on the server URL for clients that only take a URL. See regional endpoints.

Run the server locally​

To run the MCP server process on your machine instead, use the @browserless.io/mcp npm package over stdio. You need Node.js 24 or newer. Browser work still runs on Browserless, so this is mainly for pinning a server version (add it to the package name, for example @browserless.io/mcp@1.48.0) or pointing at a self-hosted instance with BROWSERLESS_API_URL. Both setups use the server name browserless, so run droid mcp remove browserless before adding this one rather than keeping both.

Add to ~/.factory/mcp.json:

{
"mcpServers": {
"browserless": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@browserless.io/mcp"],
"env": {
"BROWSERLESS_TOKEN": "${BROWSERLESS_TOKEN}"
}
}
}
}

Droid expands ${VAR_NAME} in env values when it starts the server, so set BROWSERLESS_TOKEN in your environment first, or paste the token in place of the variable.

Check the connection​

Run droid mcp list. browserless should show as connected. If you chose OAuth, it shows as needing authentication until you sign in from /mcp.

Inside a session, /mcp opens the MCP manager, where you can see the server's tools, turn the server on or off, and sign in or clear OAuth.

FAQ & Troubleshooting​

droid mcp list shows the server as failed with an error about BROWSERLESS_TOKEN

The variable isn't set in the environment Droid was launched from. Droid reads ${BROWSERLESS_TOKEN} when it connects and fails the connection if the variable is missing. Export it in your shell profile, open a new terminal, and start Droid again.

Droid asks me to sign in even though I added the token header

The entry is missing --no-oauth, or "oauth": false in mcp.json. Without it, Droid can try the OAuth flow for a remote server. Add "oauth": false to the browserless entry, or remove the server and run droid mcp add again with --no-oauth.

Should I use --type sse?

No. Use --type http. The hosted Browserless server speaks Streamable HTTP and doesn't support the legacy SSE transport.

The local server times out on first start

The first npx run downloads @browserless.io/mcp, which can take longer than Droid's 30-second stdio connect timeout. Run npx -y @browserless.io/mcp once in a terminal, stop it with Ctrl+C after it starts, then run droid mcp list again. You can also raise connectTimeout on the entry.

The server connects but every tool call returns 401 Unauthorized

The token is missing or wrong. Copy it again from your account dashboard and check the header reads Bearer followed by the token, with no quotes or trailing whitespace inside the value.

Next steps​

Was this page helpful?