Using Browserless with Dify

Dify is an open-source platform for building AI apps and workflows. This guide connects Dify to Browserless two ways: as an MCP server whose tools Dify agents can call, and as a REST API step inside a workflow.

Prerequisites

• A Browserless API token from your account dashboard
• A Dify workspace, on Dify Cloud or self-hosted, where you can manage tools
• A model provider configured in Dify that supports tool calling, for the agent examples

Which approach to use

Approach	Use it when	Where you use it
Browserless MCP server	An agent should decide when to search, scrape, or map a site	Agent apps, Agent nodes in workflows, and Tool nodes
HTTP Request node	A workflow always runs the same Browserless call at a fixed step	Workflow and Chatflow apps

Use MCP when the model should pick the tool and its arguments. Use the HTTP Request node when the step is always the same, since it costs no model calls and gives you the raw response to pass to later nodes.

Add the Browserless MCP server

Dify imports the tools of any MCP server that uses the HTTP transport. The hosted Browserless server at https://mcp.browserless.io/mcp uses Streamable HTTP, so there's nothing to install.

1. Open the MCP tools page

   In Dify, go to Integrations > Tools, open the MCP tab, and add a new MCP server.

2. Enter the server details

   • Server URL: https://mcp.browserless.io/mcp
   • Name: Browserless
   • Server identifier: browserless

   Pick the identifier carefully. Apps reference the server by it, so changing it later breaks the Browserless tools in every app that uses them.

3. Add your API token as a custom header

   Under the server's advanced options, add a custom header. MCP server headers need Dify 1.9.0 or later; on older self-hosted versions, append ?token=YOUR_API_TOKEN_HERE to the server URL instead.

   Authorization: Bearer YOUR_API_TOKEN_HERE

   Dify sends custom headers with every request to the server, and the Browserless MCP server checks this header before any other credential. Use the header rather than a ?token= query parameter so the token stays out of the server URL.

   In the same advanced options, raise the request timeout and SSE read timeout if you plan to use browserless_crawl or scrape slow pages. The defaults are fine for single-page scrapes.

4. Save and check the tool list

   Save the server. Dify connects and imports the server's tools, including browserless_smartscraper, browserless_search, browserless_map, and browserless_crawl. See the MCP tool reference for what each one does.

Use the tools in an agent

Add the Browserless tools wherever Dify accepts tools:

• Agent app: open the app, add tools, and pick the Browserless tools you want the agent to use.
• Agent node in a Workflow or Chatflow: add the same tools to the node so the agent can call them during that step.
• Tool node: call one Browserless tool as a fixed workflow step, with its arguments set from earlier nodes.

Only add the tools the agent needs. A short list, such as browserless_smartscraper, browserless_search, and browserless_map, makes the model pick the right tool more often than the full set does.

Then ask the agent something that needs the web, for example "Scrape https://news.ycombinator.com and list the top 3 stories."

Response:

Here are the top 3 stories on Hacker News right now:

1. <story title> (https://...)
2. <story title> (https://...)
3. <story title> (https://...)

The run log shows each browserless_smartscraper call with its arguments and the content it returned.

Call Browserless REST APIs from a workflow

The HTTP Request node calls any Browserless REST endpoint directly. This example scrapes a URL with the Smart Scrape API and hands the markdown to an LLM node.

1. Store your token as a secret

   In the workflow's environment variables, add a Secret variable named BROWSERLESS_TOKEN with your API token. Dify masks secret values in run logs and in the HTTP Request node's request log.

2. Add a User Input variable

   On the workflow's User Input node, add a text variable named url.

3. Add an HTTP Request node

   Configure it:

   • Method: POST
   • URL: https://production-sfo.browserless.io/smart-scrape?token= followed by the BROWSERLESS_TOKEN environment variable
   • Headers: Content-Type: application/json
   • Body: JSON

   {
     "url": "{{url}}",
     "formats": ["markdown"]
   }

   Insert url and BROWSERLESS_TOKEN with Dify's variable picker rather than typing them, so Dify binds them to the right nodes. Pass the token as the token query parameter, not in the body. Browserless REST APIs read it from the URL.

4. Use the response

   Add an LLM node after the HTTP Request node and reference the HTTP node's body output in the prompt, for example: "Summarize the markdown field of this Browserless response in three bullet points."

   Response, the HTTP Request node's body, trimmed:

   {
     "ok": true,
     "statusCode": 200,
     "strategy": "http-fetch",
     "markdown": "Hacker News\n\n[![](y18.svg)](https://news.ycombinator.com)\n\n**[Hacker News](news)**[new](newest) | ...",
     "metadata": {
       "title": "Hacker News",
       "sourceURL": "https://news.ycombinator.com",
       "statusCode": 200
     }
   }

5. Return the result

   In a Workflow app, add an Output node after the LLM node and reference the LLM node's text output, so the workflow returns the summary to the caller. In a Chatflow app, use an Answer node instead.

The same pattern works for every Browserless REST endpoint. Swap the path and body for /screenshot, /pdf, /content, or /search. Dify turns binary responses such as screenshots and PDFs into file variables you can pass to later nodes.

FAQ & Troubleshooting

The Browserless tools fail with Server error 401: Invalid API key

Dify can import the tool list without a valid token, so the server saves fine and only fails when a tool runs. Check the custom header: the name is Authorization and the value is Bearer YOUR_API_TOKEN_HERE, with a space after Bearer.

The MCP server shows as unconfigured, or no tools appear

Check that the server URL is exactly https://mcp.browserless.io/mcp, then refresh the server's tool list. That's the Streamable HTTP endpoint Dify's MCP tools expect. Don't use the legacy /sse endpoint.

The HTTP Request node returns 401 Unauthorized

The token isn't on the URL. Check that the URL ends with ?token= followed by the BROWSERLESS_TOKEN variable, and that the variable holds the token itself, not Bearer <token>.

Tool calls or HTTP requests time out on slow pages

For the MCP server, raise the request timeout and SSE read timeout in the server's advanced options. For the HTTP Request node, raise its read timeout. Dify's own maximum still applies, so for long crawls start them with a smaller limit.

Can self-hosted Dify reach a self-hosted Browserless?

Yes, but localhost inside Dify's containers points at the container itself. Use an address the Dify API container can reach, such as the Browserless container's service name on a shared Docker network, in place of https://production-sfo.browserless.io.

Dify also sends outbound requests through its SSRF proxy, which blocks private addresses by default. Set SSRF_PROXY_ALLOW_PRIVATE_IPS in Dify's .env to the narrowest range that covers the Browserless container, for example its address as a /32, then restart Dify. /smart-scrape is cloud-only, so on self-hosted Browserless call the browser-prefixed Content API route, /chromium/content. With the default self-hosted image that's plain HTTP on port 3000, for example http://browserless:3000/chromium/content?token=YOUR_TOKEN where browserless is the container's service name; use https only if you put a TLS reverse proxy in front. Drop formats from the JSON body so it reads {"url": "{{url}}"}. The response body is the page's rendered HTML rather than JSON with a markdown field, so change the LLM prompt to summarize that HTML.

Next steps

MCP tool reference

What each Browserless MCP tool does and returns

REST APIs overview

Every Browserless REST endpoint you can call from Dify

n8n templates

Browserless HTTP Request templates for n8n workflows