MCP and Tool-Call Support

[sameelarif]

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:

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:

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 for more information.

test plan

Internal agent evals.

[changeset-bot]

🦋 Changeset detected

Latest commit: ba92009

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Summary

This pull request adds Model Context Protocol (MCP) and custom tool support to Stagehand agents, significantly expanding the framework's capabilities beyond browser automation to include third-party service integrations. The changes introduce a flexible architecture where agents can connect to external MCP servers and execute custom tools alongside existing browser automation functions.

The implementation provides three ways to configure integrations: (1) simple string URLs that are internally converted to MCP connections, (2) pre-established connections using the built-in connectToMCPServer utility, and (3) custom Client objects from the @modelcontextprotocol/sdk. The agent configuration now accepts integrations and tools parameters in the AgentConfig interface.

Core architectural changes include:

• New MCP utilities: lib/mcp/connection.ts provides connectToMCPServer for establishing connections, while lib/mcp/utils.ts implements resolveTools to convert MCP tools into AI SDK's ToolSet format
• Agent client updates: Both OpenAI and Anthropic CUA clients now accept and execute custom tools alongside their computer use functionality
• Operator handler refactor: Complete rewrite from schema-based responses to a tool-calling architecture that combines built-in Stagehand operations (act, extract, goto, etc.) with external MCP tools
• Type system enhancements: New error handling with MCPConnectionError, JSON Schema to Zod conversion utilities, and updated type definitions

The changes maintain backward compatibility while enabling agents to adapt to complex web environments requiring external API access, search capabilities, database interactions, and other third-party services. Examples demonstrate real-world usage with Exa AI search integration.

Confidence score: 4/5

• This PR introduces complex new functionality but appears well-architected with proper error handling and flexible API design
• Score reflects the significant architectural changes in critical files like the operator handler, though the implementation follows good patterns
• Pay close attention to lib/handlers/operatorHandler.ts and the MCP connection utilities for potential integration issues

_{18 files reviewed, 3 comments}

_{Edit Code Review Bot Settings | Greptile}

[greptile-apps]

style: Using .refine() for enum validation instead of .enum() - this works but .enum() would be more direct for string enums

[miguelg719]

what does cursor stand for? a pointer to iterate through the listed tools?

[sameelarif]

yeah it's for handling pagination of the tools

[miguelg719]

do we want to keep experimental for context pruning? or now that it's deployed it's obsolete

[miguelg719]

table into separate pr once deployed

[miguelg719]

e2e tests failing, need to double check