Skip to content

Commit 8244ab2

Browse files
sameelarifgreptile-apps[bot]tkattkat
authored
MCP and Tool-Call Support (#981)
# why At the moment, Stagehand excels at browser automation but is limited in being able to interact with third-party services. Many production use cases require supporting these integrations. As the scope of browser agents expand, it’s becoming increasingly important that agents adapt to the web rather than the web adapting to them. # what changed Added support for integrations (MCPs) and custom tools to be passed in to the Stagehand agent. Here are some examples: ```ts const agent = stagehand.agent({ integrations: [ "https://www.example.com/mcp", ], }); ``` The above syntax will internally create the MCP connection. However, if you prefer a self-managed connection, there are two more options available. The first option is to use our built-in util to establish a connection: ```ts import { connectToMCPServer } from "@browserbasehq/stagehand" const exampleClient = await connectToMCPServer("https://www.example.com/mcp") const agent = stagehand.agent({ integrations: [exampleClient], }); ``` The alternative is to establish a connection to the MCP server with your own client. Stagehand takes in a `Client` object from the `@modelcontextprotocol/sdk` package. Please refer to their [documentation](https://modelcontextprotocol.io/docs/getting-started/intro) for more information. # test plan Internal agent evals. --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> Co-authored-by: tkattkat <[email protected]>
1 parent 760e754 commit 8244ab2

26 files changed

+1750
-299
lines changed

‎.changeset/old-forks-help.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@browserbasehq/stagehand": minor
3+
---
4+
5+
Added support for `stagehand.agent` to interact with MCP servers as well as custom tools to be passed in. For more information, reference the [MCP integrations documentation](https://docs.stagehand.dev/best-practices/mcp-integrations)

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,5 @@ eval-summary.json
1919
package-lock.json
2020
evals/deterministic/tests/BrowserContext/tmp-test.har
2121
lib/version.ts
22+
/examples/inference_summary
23+
/inference_summary

‎docs/basics/agent.mdx

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,52 @@ await agent.execute("apply for a job at Browserbase")
5454
```
5555
</CodeGroup>
5656

57+
## MCP Integrations
58+
59+
Agents can be enhanced with external tools and services through MCP (Model Context Protocol) integrations. This allows your agent to access external APIs and data sources beyond just browser interactions.
60+
61+
<CodeGroup>
62+
```typescript TypeScript (Pass URL)
63+
const agent = stagehand.agent({
64+
provider: "openai",
65+
model: "computer-use-preview",
66+
integrations: [
67+
`https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`,
68+
],
69+
instructions: `You have access to web search through Exa. Use it to find current information before browsing.`,
70+
options: {
71+
apiKey: process.env.OPENAI_API_KEY,
72+
},
73+
});
74+
75+
await agent.execute("Search for the best headphones of 2025 and go through checkout for the top recommendation");
76+
```
77+
78+
```typescript TypeScript (Create Connection)
79+
import { connectToMCPServer } from "@browserbasehq/stagehand";
80+
81+
const supabaseClient = await connectToMCPServer(
82+
`https://server.smithery.ai/@supabase-community/supabase-mcp/mcp?api_key=${process.env.SMITHERY_API_KEY}`
83+
);
84+
85+
const agent = stagehand.agent({
86+
provider: "openai",
87+
model: "computer-use-preview",
88+
integrations: [supabaseClient],
89+
instructions: `You can interact with Supabase databases. Use these tools to store and retrieve data.`,
90+
options: {
91+
apiKey: process.env.OPENAI_API_KEY,
92+
},
93+
});
94+
95+
await agent.execute("Search for restaurants and save the first result to the database");
96+
```
97+
</CodeGroup>
98+
99+
<Tip>
100+
MCP integrations enable agents to be more powerful by combining browser automation with external APIs, databases, and services. The agent can intelligently decide when to use browser actions versus external tools.
101+
</Tip>
102+
57103
<Warning>
58104
Stagehand uses a 1024x768 viewport by default (the optimal size for Computer Use Agents). Other viewport sizes may reduce performance. If you need to modify the viewport, you can edit in the [Browser Configuration](/configuration/browser).
59105
</Warning>

‎docs/best-practices/mcp-integrations.mdx

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
---
2+
title: "MCP Integrations"
3+
description: "Using Model Context Protocol (MCP) integrations to enhance agent capabilities"
4+
---
5+
6+
## What are MCP Integrations?
7+
8+
MCP (Model Context Protocol) integrations allow you to connect your Stagehand agents to external tools, APIs, and services. This enables agents to perform actions beyond browser automation, such as web search, database operations, and API calls.
9+
10+
<Info>
11+
MCP integrations make your agents more powerful by combining browser automation with external capabilities. The agent can intelligently decide when to use browser actions versus external tools.
12+
</Info>
13+
14+
## Connection Options
15+
16+
There are two options for connecting to MCP servers:
17+
18+
1. **Pass a URL directly** - The simplest approach for quick setup
19+
2. **Create a connection first** - Gives you more control over the connection
20+
21+
## Passing a URL
22+
23+
The simplest way to add MCP integrations is by providing server URLs directly in the agent configuration:
24+
25+
```typescript
26+
const agent = stagehand.agent({
27+
provider: "openai",
28+
model: "computer-use-preview",
29+
integrations: [
30+
`https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`,
31+
],
32+
instructions: `You have access to web search through Exa. Use it to find current information before browsing.`,
33+
options: {
34+
apiKey: process.env.OPENAI_API_KEY,
35+
},
36+
});
37+
38+
await agent.execute("Search for the best headphones of 2025 and go through checkout for the top recommendation");
39+
```
40+
41+
## Creating a Connection First
42+
43+
Alternatively, you can establish MCP connections first and then pass the client objects:
44+
45+
```typescript
46+
import { connectToMCPServer } from "@browserbasehq/stagehand";
47+
48+
// Connect to MCP server
49+
const supabaseClient = await connectToMCPServer(
50+
`https://server.smithery.ai/@supabase-community/supabase-mcp/mcp?api_key=${process.env.SMITHERY_API_KEY}`
51+
);
52+
53+
// Use the connected client
54+
const agent = stagehand.agent({
55+
provider: "openai",
56+
model: "computer-use-preview",
57+
integrations: [supabaseClient],
58+
instructions: `You can interact with Supabase databases. Use these tools to store and retrieve data.`,
59+
options: {
60+
apiKey: process.env.OPENAI_API_KEY,
61+
},
62+
});
63+
64+
await agent.execute("Search for restaurants in New Brunswick, NJ and save the first result to the database");
65+
```
66+
67+
68+
69+
## Multiple Integrations
70+
71+
You can combine multiple MCP integrations in a single agent:
72+
73+
```typescript
74+
const databaseClient = await connectToMCPServer(/* database config */);
75+
76+
const agent = stagehand.agent({
77+
integrations: [
78+
`https://search-service.example.com/mcp?apiKey=${process.env.SEARCH_API_KEY}`,
79+
databaseClient
80+
],
81+
instructions: `You have access to external tools for search and data storage. Use these tools strategically to complete tasks efficiently.`
82+
});
83+
```
84+
85+
## Best Practices
86+
87+
### Choose the Right Connection Approach
88+
<Tabs>
89+
<Tab title="Passing a URL">
90+
**When to use:**
91+
- Simple setup requirements
92+
- Standard API configurations
93+
- Getting started quickly
94+
95+
**Benefits:**
96+
- Minimal code required
97+
- Automatic connection handling
98+
- Easy to configure
99+
</Tab>
100+
101+
<Tab title="Creating a Connection First">
102+
**When to use:**
103+
- Custom connection options
104+
- Connection reuse across agents
105+
- Advanced error handling
106+
107+
**Benefits:**
108+
- Full control over connections
109+
- Better error handling
110+
- Connection pooling capabilities
111+
</Tab>
112+
</Tabs>
113+
114+
### Environment Variables
115+
116+
Always use environment variables for API keys and sensitive information:
117+
118+
```bash
119+
# .env file
120+
SEARCH_API_KEY=your_search_service_key
121+
MCP_SERVICE_API_KEY=your_mcp_service_key
122+
OPENAI_API_KEY=your_openai_key
123+
DATABASE_URL=your_database_url
124+
DATABASE_API_KEY=your_database_key
125+
```
126+
127+
### Instructions Best Practices
128+
129+
Provide clear instructions about available tools:
130+
131+
<Tabs>
132+
<Tab title="Good Instructions">
133+
```typescript
134+
instructions: `You have access to:
135+
1. Web search tools - Use to find current information
136+
2. Database tools - Use to store/retrieve data
137+
3. Browser automation - Use for web interactions
138+
139+
Always search for current information before making decisions.
140+
Store important data for later reference.`
141+
```
142+
</Tab>
143+
144+
<Tab title="Poor Instructions">
145+
```typescript
146+
instructions: "You can search and save data."
147+
```
148+
</Tab>
149+
</Tabs>
150+
151+
### Error Handling
152+
153+
Implement proper error handling for MCP connections:
154+
155+
```typescript
156+
try {
157+
const client = await connectToMCPServer(serverUrl);
158+
159+
const agent = stagehand.agent({
160+
integrations: [client],
161+
// ... other config
162+
});
163+
164+
const result = await agent.execute(instruction);
165+
} catch (error) {
166+
console.error("MCP integration failed:", error);
167+
// Handle fallback behavior
168+
}
169+
```
170+
171+
## Troubleshooting
172+
173+
<AccordionGroup>
174+
<Accordion title="Connection timeouts">
175+
**Problem:** MCP server connections timing out
176+
177+
**Solutions:**
178+
- Verify server URLs are correct and accessible
179+
- Check network connectivity
180+
- Ensure API keys are valid and have proper permissions
181+
- Try connecting to servers individually to isolate issues
182+
</Accordion>
183+
184+
<Accordion title="Tool not being used">
185+
**Problem:** Agent not using available MCP tools
186+
187+
**Solutions:**
188+
- Make instructions more specific about when to use tools
189+
- Ensure API keys are properly configured
190+
- Check that the MCP server supports the expected tools
191+
- Verify tool descriptions are clear and actionable
192+
</Accordion>
193+
194+
<Accordion title="Authentication errors">
195+
**Problem:** API key or authentication failures
196+
197+
**Solutions:**
198+
- Verify all required environment variables are set
199+
- Check API key validity and permissions
200+
- Ensure URLs include necessary authentication parameters
201+
- Test MCP connections independently before using in agents
202+
</Accordion>
203+
</AccordionGroup>
204+
205+
## Examples
206+
207+
### Web Search + Browser Automation
208+
```typescript
209+
const agent = stagehand.agent({
210+
integrations: [`https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`],
211+
instructions: `First search for current information, then use the browser to complete tasks based on what you find.`
212+
});
213+
214+
await agent.execute("Find the best laptop deals for 2025 and navigate to purchase the top recommendation");
215+
```
216+
217+
### Data Extraction + Storage
218+
```typescript
219+
const supabaseClient = await connectToMCPServer(/* config */);
220+
221+
const agent = stagehand.agent({
222+
integrations: [supabaseClient],
223+
instructions: `Extract data from websites and store it using available database tools.`
224+
});
225+
226+
await agent.execute("Extract all restaurant information from this directory and save it to the database");
227+
```
228+
229+
### Multi-tool Workflow
230+
```typescript
231+
const agent = stagehand.agent({
232+
integrations: [
233+
`https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`,
234+
supabaseClient
235+
],
236+
instructions: `Use all available tools strategically: search for current info, browse websites, and store important data.`
237+
});
238+
239+
await agent.execute("Research competitor pricing, compare with our site, and store the analysis");
240+
```
241+
242+
## Further Reading
243+
244+
<CardGroup cols={3}>
245+
<Card title="Agent Basics" icon="robot" href="/basics/agent">
246+
Learn the fundamentals of Stagehand agents
247+
</Card>
248+
249+
<Card title="MCP Server Setup" icon="server" href="/integrations/mcp/setup">
250+
Set up your own MCP server
251+
</Card>
252+
253+
<Card title="Custom Tools" icon="wrench" href="/integrations/mcp/tools">
254+
Create custom MCP tools
255+
</Card>
256+
</CardGroup>

‎docs/docs.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
"best-practices/build-agent",
6060
"best-practices/agent-fallbacks",
6161
"best-practices/prompting-best-practices",
62+
"best-practices/mcp-integrations",
6263
"best-practices/speed-optimization"
6364
]
6465
},

‎docs/integrations/mcp/introduction.mdx

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,14 @@ The Browserbase MCP Server brings powerful browser automation capabilities to Cl
1212
This server enables Claude to control browsers, navigate websites, interact with web elements, and extract data—all through simple conversational commands.
1313
</Info>
1414

15+
<Note>
16+
**Two Ways to Use MCP:**
17+
1. **Browserbase MCP Server**: Provides browser automation tools to Claude Desktop and other MCP clients
18+
2. **MCP Integrations in Stagehand**: Add external tools (like Exa search, Supabase) to Stagehand agents
19+
20+
This documentation covers the Browserbase MCP Server. For using MCP integrations within Stagehand agents, see [MCP Integrations](/best-practices/mcp-integrations).
21+
</Note>
22+
1523
## Key Features
1624

1725
<CardGroup cols={2}>

‎docs/references/agent.mdx

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ interface AgentConfig {
2727
model?: string;
2828
instructions?: string;
2929
options?: Record<string, unknown>;
30+
integrations?: (Client | string)[];
31+
tools?: ToolSet;
3032
}
3133
```
3234

@@ -78,6 +80,18 @@ agent = stagehand.agent({
7880
**Common:** `apiKey`, `baseURL`, `organization`
7981
</ParamField>
8082

83+
<ParamField path="integrations" type="(Client | string)[]" optional>
84+
MCP (Model Context Protocol) integrations for external tools and services.
85+
86+
**Array of:** MCP server URLs (strings) or connected Client objects
87+
</ParamField>
88+
89+
<ParamField path="tools" type="ToolSet" optional>
90+
Custom tool definitions to extend agent capabilities.
91+
92+
**Format:** Object with tool name keys and tool definition values
93+
</ParamField>
94+
8195
### Execute Method
8296

8397
<Tabs>

0 commit comments

Comments
 (0)