From 4dee16e90d5f7c56756591de406a7145af84cec7 Mon Sep 17 00:00:00 2001
From: Anderson Martinez <anderson@browserless.io>
Date: Fri, 8 May 2026 14:37:29 -0500
Subject: [PATCH] docs: add Browserless MCP browser automation example

---
 .../config/vocabularies/AgnoStyle/accept.txt  |  1 +
 docs.json                                     |  1 +
 examples/tools/mcp/browserless.mdx            | 94 +++++++++++++++++++
 3 files changed, 96 insertions(+)
 create mode 100644 examples/tools/mcp/browserless.mdx

diff --git a/agno-docs-style/styles/config/vocabularies/AgnoStyle/accept.txt b/agno-docs-style/styles/config/vocabularies/AgnoStyle/accept.txt
index 832d07437..937549856 100644
--- a/agno-docs-style/styles/config/vocabularies/AgnoStyle/accept.txt
+++ b/agno-docs-style/styles/config/vocabularies/AgnoStyle/accept.txt
@@ -77,6 +77,7 @@ bots
 bottlenecked
 Brandfetch
 Browserbase
+Browserless
 build_image
 cache_session
 Cartesia
diff --git a/docs.json b/docs.json
index 4726784c0..7c9fdd4ac 100644
--- a/docs.json
+++ b/docs.json
@@ -6595,6 +6595,7 @@
                   "examples/tools/mcp/agno-mcp",
                   "examples/tools/mcp/airbnb",
                   "examples/tools/mcp/brave",
+                  "examples/tools/mcp/browserless",
                   "examples/tools/mcp/cli",
                   "examples/tools/mcp/filesystem",
                   "examples/tools/mcp/gibsonai",
diff --git a/examples/tools/mcp/browserless.mdx b/examples/tools/mcp/browserless.mdx
new file mode 100644
index 000000000..462af6348
--- /dev/null
+++ b/examples/tools/mcp/browserless.mdx
@@ -0,0 +1,94 @@
+---
+title: "MCP Browserless Agent"
+description: "Creates an agent that uses Anthropic to drive a real browser via the Browserless MCP server."
+---
+```python
+"""MCP Browserless Agent - Hosted browser automation
+
+This example shows how to create an agent that uses Anthropic to drive a real browser
+via the Browserless MCP server. The hosted endpoint at https://mcp.browserless.io/mcp
+exposes 10 tools, including a multi-turn `browserless_agent` that preserves browser
+state across calls — Agno's `MCPTools` keeps one MCP session alive for the lifetime
+of the `async with` block, so multi-step navigate → snapshot → click flows work
+without any session-management code.
+
+Get a Browserless API key from https://account.browserless.io
+
+Run: `uv pip install agno anthropic mcp` to install the dependencies
+"""
+
+import asyncio
+import logging
+from os import getenv
+
+from agno.agent import Agent
+from agno.models.anthropic import Claude
+from agno.tools.mcp import MCPTools, StreamableHTTPClientParams
+from agno.utils.pprint import apprint_run_response
+
+# Silence an MCP SDK pydantic validation warning on server progress notifications.
+# Harmless and unrelated to tool call results.
+logging.getLogger().addFilter(
+    lambda r: "Failed to validate notification" not in r.getMessage()
+)
+
+# ---------------------------------------------------------------------------
+# Create Agent
+# ---------------------------------------------------------------------------
+
+
+async def run_agent(message: str) -> None:
+    async with MCPTools(
+        url="https://mcp.browserless.io/mcp",
+        transport="streamable-http",
+        timeout_seconds=120,
+        server_params=StreamableHTTPClientParams(
+            url="https://mcp.browserless.io/mcp",
+            headers={
+                "Authorization": f"Bearer {getenv('BROWSERLESS_TOKEN')}",
+            },
+        ),
+    ) as mcp_tools:
+        agent = Agent(
+            model=Claude(id="claude-sonnet-4-6"),
+            tools=[mcp_tools],
+            instructions=(
+                "You drive a real browser via the browserless_agent tool. "
+                "Snapshot the page before extracting elements; use selector "
+                "references from the snapshot when calling text/click."
+            ),
+            markdown=True,
+        )
+
+        response_stream = await agent.arun(message)
+        await apprint_run_response(response_stream)
+
+
+# ---------------------------------------------------------------------------
+# Run Agent
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    asyncio.run(
+        run_agent(
+            "Use browserless_agent to navigate to https://news.ycombinator.com, "
+            "click the first story link, and report the title and first paragraph "
+            "of that page."
+        )
+    )
+```
+
+## Run the Example
+```bash
+# Install dependencies
+uv pip install agno anthropic mcp
+
+# Set environment variables
+export BROWSERLESS_TOKEN="***"
+export ANTHROPIC_API_KEY="***"
+
+# Save the script above as browserless.py and run it
+python browserless.py
+```
+
+Runnable cookbook with stateless and multi-turn examples: [browserless/browserless-agno](https://github.com/browserless/browserless-agno).