Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

add new mcp docs

ShawnPana5a3683526404
diff --git a/docs/customize/integrations/mcp-server.mdx b/docs/customize/integrations/mcp-server.mdx
index cd536c206..9397ac1da 100644
--- a/docs/customize/integrations/mcp-server.mdx
+++ b/docs/customize/integrations/mcp-server.mdx
@@ -1,33 +1,20 @@
---
-title: "Browser Automation MCP"
-description: "Connect AI assistants to browser-use via Model Context Protocol - cloud or self-hosted"
-icon: "server"
-mode: "wide"
+title: MCP Server
+description: Connect AI models to Browser Use through the Model Context Protocol
---
-## Overview
-
-Browser-use provides two ways to expose browser automation capabilities to AI assistants via the Model Context Protocol (MCP):
-
-1. **Cloud MCP Server** (recommended) - Hosted service with simple setup and managed infrastructure
-2. **Local Self-Hosted MCP** - Free, open-source option running on your machine
-
-Both enable AI assistants like Claude Desktop, Claude Code, and other MCP-compatible clients to perform web automation tasks.
-
-## Cloud MCP Server (Recommended)
-
-Browser Use provides a hosted **Model Context Protocol (MCP)** server that enables AI assistants to control browser automation. Works with any HTTP-based MCP client.
+Browser Use provides a hosted **Model Context Protocol (MCP)** server that enables AI assistants to control browser automation. Works with any HTTP-based MCP client, including Claude Code.
**MCP Server URL:** `https://api.browser-use.com/mcp`
-This is an **HTTP-based MCP server** designed for cloud integrations and remote access with managed infrastructure, persistent authentication profiles, and simplified setup.
+This is an **HTTP-based MCP server** designed for cloud integrations and remote access. If you need a local stdio-based MCP server for Claude Desktop, use the free open-source version: `uvx browser-use --mcp`
-### Quick Setup
+## Quick Setup
-#### 1. Get API Key
+### 1. Get API Key
Get your API key from the [Browser Use Dashboard](https://cloud.browser-use.com)
-#### 2. Connect Your AI
+### 2. Connect Your AI
<Tabs>
<Tab title="Claude Code">
@@ -69,7 +56,9 @@ Add to `~/.cursor/mcp.json`:
"command": "npx",
"args": [
"mcp-remote",
- "https://api.browser-use.com/mcp"
+ "https://api.browser-use.com/mcp",
+ "--header",
+ "X-Browser-Use-API-Key: your-api-key"
]
}
}
@@ -85,34 +74,61 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
"browser-use": {
"serverUrl": "https://api.browser-use.com/mcp",
"headers": {
- "X-Browser-Use-API-Key": "Your-API-Key-Here"
+ "X-Browser-Use-API-Key": "your-api-key"
}
}
}
}
```
</Tab>
+<Tab title="ChatGPT">
+**Step 1: Register an OAuth client**
+
+Call the dynamic client registration endpoint with ChatGPT's redirect URI:
+
+```bash
+curl -X POST https://api.browser-use.com/oauth/register \
+ -H "Content-Type: application/json" \
+ -d '{
+ "client_name": "ChatGPT Integration",
+ "redirect_uris": ["https://chatgpt.com/connector_platform_oauth_redirect"]
+ }'
+```
+
+Save the `client_id` from the response (43-character random string).
+
+**Step 2: Configure ChatGPT**
+
+In ChatGPT, add a custom MCP connector:
+- **MCP Server URL**: `https://api.browser-use.com/mcp/chatgpt`
+- **Client ID**: Paste the `client_id` from step 1
+
+**Step 3: Authorize**
+
+ChatGPT will redirect you to Browser Use's authorization page. Sign in and grant permission.
+
+**Note:** ChatGPT uses OAuth 2.1 authentication instead of API keys. You only need to register your client once.
+</Tab>
</Tabs>
-### Available Tools
+## Available Tools
-The cloud MCP server provides three high-level tools:
+The MCP server provides three tools:
-#### `browser_task`
+### `browser_task`
Creates and runs a browser automation task.
- **task** (required): What you want the browser to do
- **max_steps** (optional): Max actions to take (1-10, default: 8)
-- **use_profile** (optional): Use a cloud profile for persistent authentication (default: false)
-- **profile_id** (optional): UUID of the profile to use (required when use_profile=true)
+- **profile_id** (optional): UUID of the cloud profile to use for persistent authentication
-#### `list_browser_profiles`
+### `list_browser_profiles`
Lists all available cloud browser profiles for the authenticated project. Profiles store persistent authentication (cookies, sessions) for websites requiring login.
-#### `monitor_task`
+### `monitor_task`
Checks the current status and progress of a browser automation task. Returns immediately with a snapshot of the task state.
-- **session_id** (required): UUID of the session to monitor (returned by browser_task)
+- **task_id** (required): UUID of the task to monitor (returned by browser_task)
-### Example Usage
+## Example Usage
Once connected, ask your AI to perform web tasks:
@@ -124,9 +140,9 @@ Once connected, ask your AI to perform web tasks:
The AI will use the browser tools automatically to complete these tasks.
-### Smart Features
+## Smart Features
-**Cloud Profiles for Authentication**
+### Cloud Profiles for Authentication
Use cloud browser profiles to maintain persistent login sessions across tasks. Profiles store cookies and authentication state for:
- Social media (X/Twitter, LinkedIn, Facebook)
- Email (Gmail, Outlook)
@@ -135,12 +151,26 @@ Use cloud browser profiles to maintain persistent login sessions across tasks. P
List available profiles with `list_browser_profiles`, then pass the `profile_id` to `browser_task`.
-**Real-time Task Monitoring**
+### Real-time Task Monitoring
Use `monitor_task` to check task progress while it's running. The tool returns immediately with the current status, latest step details, and agent reasoning. Call it repeatedly to track progress live.
-**Conversational Progress Summaries**
+### Conversational Progress Summaries
When you monitor tasks, the AI automatically interprets step data into natural language updates, explaining what the browser has completed and what it's currently working on.
+## Troubleshooting
+
+**Connection issues?**
+- Verify your API key is correct
+- Check you're using the right headers
+
+**Task taking too long?**
+- Check the live_url to see progress
+- Increase max_steps for complex tasks (max: 10)
+- Use clearer, more specific instructions
+
+**Need help?**
+Check the [v2 API Reference](/api-reference/v2) for detailed specifications.
+
---
## Local Self-Hosted Alternative