From 341d0315956f31c82cf758f55dbf2bc26f38d3c4 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:30:37 +0000 Subject: [PATCH 1/3] docs(mastra): lead with the supported MCPClient setup --- packages/docs/v4/integrations/mastra.mdx | 62 +++++++++++++++++++++++- packages/integrations/mastra/README.md | 5 ++ 2 files changed, 65 insertions(+), 2 deletions(-) diff --git a/packages/docs/v4/integrations/mastra.mdx b/packages/docs/v4/integrations/mastra.mdx index b08f14bc6..cc9badd0a 100644 --- a/packages/docs/v4/integrations/mastra.mdx +++ b/packages/docs/v4/integrations/mastra.mdx @@ -6,9 +6,67 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st The Mastra integration connects an agent to the Stagehand facade MCP server over MCP/stdio. The MCP client remains open for the agent run, so browser state survives across tool calls. -Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter. +The source example is maintained in the Stagehand repository. For an existing application, prefer the host’s MCP client and the packaged server described below. +## Add Stagehand to an existing agent + +Use Mastra’s supported tool integration: `MCPClient` from `@mastra/mcp`. This is an [official SDK/MCP extension point](https://mastra.ai/docs/agents/tools); a separate host plugin marketplace is not required. + + +The portable setup below requires the first `@browserbasehq/stagehand-mcp@0.1.0` release. Until that release is published, use the source example further down this page. Node.js 24+ is required to run the MCP server. + + +Install the host libraries in your application: + +```bash +pnpm add @mastra/core @mastra/mcp +``` + +Configure your agent’s model credentials as usual. The browser uses local Chrome unless you export `BROWSERBASE_API_KEY`. Only browser configuration is forwarded to the MCP child. + +```typescript +import { MCPClient } from "@mastra/mcp"; +import { Agent } from "@mastra/core/agent"; + +const env = Object.fromEntries( + Object.entries(process.env).filter( + (entry): entry is [string, string] => + (entry[0].startsWith("STAGEHAND_") || entry[0].startsWith("BROWSERBASE_")) && + entry[1] !== undefined, + ), +); +const client = new MCPClient({ + id: "stagehand-browser", + servers: { + stagehand: { + command: "npx", + args: ["-y", "@browserbasehq/stagehand-mcp@0.1.0"], + env, + }, + }, +}); + +try { + const tools = await client.listTools(); + const agent = new Agent({ + id: "browser-agent", + name: "Browser agent", + instructions: "Use the Stagehand tools to browse. Take a snapshot before interacting with page elements.", + model: "openai/gpt-5.6-luna", + tools, + }); + const result = await agent.generate("Open https://example.com and report its title.", { + maxSteps: 20, + }); + console.log(result.text); +} finally { + await client.disconnect(); +} +``` + +Keep the connection open until the entire agent run finishes. Closing it releases the server and its browser. + ## Prerequisites - Node.js 24 or newer @@ -16,7 +74,7 @@ Stagehand ships this experimental integration from the repository rather than pu - An OpenAI API key for the example agent - A current Google Chrome installation for local browser mode -## Quickstart +## Run the source example diff --git a/packages/integrations/mastra/README.md b/packages/integrations/mastra/README.md index 8b2e03da8..314861936 100644 --- a/packages/integrations/mastra/README.md +++ b/packages/integrations/mastra/README.md @@ -1,5 +1,10 @@ # Mastra + Stagehand facade over MCP/stdio +## Supported integration route + +Use `MCPClient` from `@mastra/mcp`, as described in the [official Mastra documentation](https://mastra.ai/docs/agents/tools). No separate host marketplace plugin is needed. The [Stagehand guide](https://docs.stagehand.dev/v4/integrations/mastra#add-stagehand-to-an-existing-agent) includes a portable setup using the packaged MCP server, pending its first 0.1.0 release. The source example below remains available before publication. + + This example connects Mastra to the Stagehand facade MCP server over stdio. It exposes the facade's `run`, `snapshot`, and `screenshot` tools to a Mastra agent, using agent instructions imported from the integrations package. From d41e27278f3bb0fd27a43cb8196816abd30ef25c Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:33:30 +0000 Subject: [PATCH 2/3] style: format integration documentation and configuration --- packages/integrations/mastra/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/integrations/mastra/README.md b/packages/integrations/mastra/README.md index 314861936..03e06630c 100644 --- a/packages/integrations/mastra/README.md +++ b/packages/integrations/mastra/README.md @@ -4,7 +4,6 @@ Use `MCPClient` from `@mastra/mcp`, as described in the [official Mastra documentation](https://mastra.ai/docs/agents/tools). No separate host marketplace plugin is needed. The [Stagehand guide](https://docs.stagehand.dev/v4/integrations/mastra#add-stagehand-to-an-existing-agent) includes a portable setup using the packaged MCP server, pending its first 0.1.0 release. The source example below remains available before publication. - This example connects Mastra to the Stagehand facade MCP server over stdio. It exposes the facade's `run`, `snapshot`, and `screenshot` tools to a Mastra agent, using agent instructions imported from the integrations package. From 11b72210037417c1008f0302879c4c9d52b14b76 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:37:25 +0000 Subject: [PATCH 3/3] docs: clarify MCP runtime and credential forwarding --- packages/docs/v4/integrations/mastra.mdx | 6 +++--- packages/integrations/mastra/README.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/docs/v4/integrations/mastra.mdx b/packages/docs/v4/integrations/mastra.mdx index cc9badd0a..d82f7b29d 100644 --- a/packages/docs/v4/integrations/mastra.mdx +++ b/packages/docs/v4/integrations/mastra.mdx @@ -6,12 +6,12 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st The Mastra integration connects an agent to the Stagehand facade MCP server over MCP/stdio. The MCP client remains open for the agent run, so browser state survives across tool calls. -The source example is maintained in the Stagehand repository. For an existing application, prefer the host’s MCP client and the packaged server described below. +The source example is maintained in the Stagehand repository. For an existing application, prefer the host’s MCP client and the Stagehand facade MCP server described below. ## Add Stagehand to an existing agent -Use Mastra’s supported tool integration: `MCPClient` from `@mastra/mcp`. This is an [official SDK/MCP extension point](https://mastra.ai/docs/agents/tools); a separate host plugin marketplace is not required. +Use Mastra’s supported tool integration: `MCPClient` from `@mastra/mcp`. This is an [official SDK/MCP extension point](https://mastra.ai/docs/agents/tools); you do not need a separate host marketplace plugin. The portable setup below requires the first `@browserbasehq/stagehand-mcp@0.1.0` release. Until that release is published, use the source example further down this page. Node.js 24+ is required to run the MCP server. @@ -23,7 +23,7 @@ Install the host libraries in your application: pnpm add @mastra/core @mastra/mcp ``` -Configure your agent’s model credentials as usual. The browser uses local Chrome unless you export `BROWSERBASE_API_KEY`. Only browser configuration is forwarded to the MCP child. +Configure your agent’s model credentials as usual. The browser uses local Chrome unless you export `BROWSERBASE_API_KEY`. The Mastra host forwards the `STAGEHAND_*` and `BROWSERBASE_*` variables to the MCP child, including any separate Stagehand model configuration. Your agent’s model-provider credential stays in the host. ```typescript import { MCPClient } from "@mastra/mcp"; diff --git a/packages/integrations/mastra/README.md b/packages/integrations/mastra/README.md index 03e06630c..68d844ae2 100644 --- a/packages/integrations/mastra/README.md +++ b/packages/integrations/mastra/README.md @@ -2,7 +2,7 @@ ## Supported integration route -Use `MCPClient` from `@mastra/mcp`, as described in the [official Mastra documentation](https://mastra.ai/docs/agents/tools). No separate host marketplace plugin is needed. The [Stagehand guide](https://docs.stagehand.dev/v4/integrations/mastra#add-stagehand-to-an-existing-agent) includes a portable setup using the packaged MCP server, pending its first 0.1.0 release. The source example below remains available before publication. +Use `MCPClient` from `@mastra/mcp`, as described in the [official Mastra documentation](https://mastra.ai/docs/agents/tools). You do not need a separate host marketplace plugin. The [Stagehand guide](https://docs.stagehand.dev/v4/integrations/mastra#add-stagehand-to-an-existing-agent) includes a portable setup using the Stagehand facade MCP server (`@browserbasehq/stagehand-mcp`), pending its first 0.1.0 release. The source example below remains available before publication. This example connects Mastra to the Stagehand facade MCP server over stdio. It exposes the facade's `run`, `snapshot`, and `screenshot` tools to a Mastra agent,