Conversation
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
6 issues found and verified against the latest diff
Confidence score: 4/5
- In
packages/docs/v4/integrations/mastra.mdx, thefinallycleanup can let a rejectingdisconnect()hide the original discovery or agent-generation failure, making diagnosis misleading—catch cleanup errors while preserving and reporting the primary failure. - In
packages/docs/v4/integrations/mastra.mdx, the claim that only browser configuration crosses the boundary conflicts with forwarding everySTAGEHAND_*variable, includingSTAGEHAND_MODEL_API_KEY, which could mislead users about credential exposure—document the complete allowlist and model-key handling. - The integration documentation in
packages/docs/v4/integrations/mastra.mdxandpackages/integrations/mastra/README.mduses inconsistent or passive descriptions and leaves the runtime/package implicit; name the Stagehand facade MCP server and@browserbasehq/stagehand-mcp@0.1.0, and revise the prose to identify the actor clearly.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/integrations/mastra/README.md">
<violation number="1" location="packages/integrations/mastra/README.md:5">
P3: The new route leaves the runtime and npm package implicit by calling it only a “packaged MCP server.” Name the Stagehand facade MCP server and `@browserbasehq/stagehand-mcp@0.1.0` here so this README matches the launched process and linked setup.
(Based on your team's feedback about precise facade runtime names in MCP integration docs.)</violation>
<violation number="2" location="packages/integrations/mastra/README.md:5">
P2: Custom agent: **Stagehand docs prose guide**
The added sentence uses passive voice: “No separate host marketplace plugin is needed.” Rewrite it as “You don’t need a separate host marketplace plugin.”</violation>
</file>
<file name="packages/docs/v4/integrations/mastra.mdx">
<violation number="1" location="packages/docs/v4/integrations/mastra.mdx:9">
P3: Use `Stagehand facade MCP server` here instead of `packaged server` so this guide identifies the actual child runtime consistently with the other MCP integration docs.</violation>
<violation number="2" location="packages/docs/v4/integrations/mastra.mdx:9">
P2: Custom agent: **Stagehand docs prose guide**
Use active voice and name the actor in these added sentences: “Stagehand maintains the source example in its repository” and “You forward only browser configuration to the MCP child.”</violation>
<violation number="3" location="packages/docs/v4/integrations/mastra.mdx:26">
P2: Although this sentence says only browser configuration crosses the boundary, the filter forwards every `STAGEHAND_*` variable, including `STAGEHAND_MODEL_API_KEY`. State the full allowlist and explain that Stagehand model credentials are separate from the agent credential, or narrow the filter.</violation>
<violation number="4" location="packages/docs/v4/integrations/mastra.mdx:64">
P2: When discovery or agent generation fails and `disconnect()` also rejects, this `finally` replaces the primary error with the cleanup failure. Catch and report disconnect errors while preserving the original failure.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| 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. |
Contributor
There was a problem hiding this comment.
P2: Although this sentence says only browser configuration crosses the boundary, the filter forwards every STAGEHAND_* variable, including STAGEHAND_MODEL_API_KEY. State the full allowlist and explain that Stagehand model credentials are separate from the agent credential, or narrow the filter.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/mastra.mdx, line 26:
<comment>Although this sentence says only browser configuration crosses the boundary, the filter forwards every `STAGEHAND_*` variable, including `STAGEHAND_MODEL_API_KEY`. State the full allowlist and explain that Stagehand model credentials are separate from the agent credential, or narrow the filter.</comment>
<file context>
@@ -6,17 +6,75 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st
+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
</file context>
Suggested change
| 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 MCP child receives exported `STAGEHAND_*` and `BROWSERBASE_*` variables, including separate Stagehand model credentials when configured. |
| }); | ||
| console.log(result.text); | ||
| } finally { | ||
| await client.disconnect(); |
Contributor
There was a problem hiding this comment.
P2: When discovery or agent generation fails and disconnect() also rejects, this finally replaces the primary error with the cleanup failure. Catch and report disconnect errors while preserving the original failure.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/mastra.mdx, line 64:
<comment>When discovery or agent generation fails and `disconnect()` also rejects, this `finally` replaces the primary error with the cleanup failure. Catch and report disconnect errors while preserving the original failure.</comment>
<file context>
@@ -6,17 +6,75 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st
+ });
+ console.log(result.text);
+} finally {
+ await client.disconnect();
+}
+```
</file context>
Suggested change
| await client.disconnect(); | |
| await client.disconnect().catch((disconnectError) => { | |
| console.error( | |
| `Warning: failed to disconnect MCP client: ${disconnectError instanceof Error ? disconnectError.message : String(disconnectError)}`, | |
| ); | |
| }); |
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
P2: Custom agent: Stagehand docs prose guide
The added sentence uses passive voice: “No separate host marketplace plugin is needed.” Rewrite it as “You don’t need a separate host marketplace plugin.”
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/integrations/mastra/README.md, line 5:
<comment>The added sentence uses passive voice: “No separate host marketplace plugin is needed.” Rewrite it as “You don’t need a separate host marketplace plugin.”</comment>
<file context>
@@ -1,5 +1,10 @@
+## 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.
+
+
</file context>
|
|
||
| <Note> | ||
| 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. |
Contributor
There was a problem hiding this comment.
P2: Custom agent: Stagehand docs prose guide
Use active voice and name the actor in these added sentences: “Stagehand maintains the source example in its repository” and “You forward only browser configuration to the MCP child.”
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/mastra.mdx, line 9:
<comment>Use active voice and name the actor in these added sentences: “Stagehand maintains the source example in its repository” and “You forward only browser configuration to the MCP child.”</comment>
<file context>
@@ -6,17 +6,75 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st
<Note>
-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.
</Note>
</file context>
|
|
||
| ## 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. |
Contributor
There was a problem hiding this comment.
P3: The new route leaves the runtime and npm package implicit by calling it only a “packaged MCP server.” Name the Stagehand facade MCP server and @browserbasehq/stagehand-mcp@0.1.0 here so this README matches the launched process and linked setup.
(Based on your team's feedback about precise facade runtime names in MCP integration docs.)
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/integrations/mastra/README.md, line 5:
<comment>The new route leaves the runtime and npm package implicit by calling it only a “packaged MCP server.” Name the Stagehand facade MCP server and `@browserbasehq/stagehand-mcp@0.1.0` here so this README matches the launched process and linked setup.
(Based on your team's feedback about precise facade runtime names in MCP integration docs.) </comment>
<file context>
@@ -1,5 +1,10 @@
+## 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.
+
+
</file context>
Suggested change
| 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). 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 Stagehand facade MCP server (`@browserbasehq/stagehand-mcp@0.1.0`), pending its first release. The source example below remains available before publication. |
|
|
||
| <Note> | ||
| 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. |
Contributor
There was a problem hiding this comment.
P3: Use Stagehand facade MCP server here instead of packaged server so this guide identifies the actual child runtime consistently with the other MCP integration docs.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/mastra.mdx, line 9:
<comment>Use `Stagehand facade MCP server` here instead of `packaged server` so this guide identifies the actual child runtime consistently with the other MCP integration docs.</comment>
<file context>
@@ -6,17 +6,75 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st
<Note>
-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.
</Note>
</file context>
Suggested change
| 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. |
Contributor
There was a problem hiding this comment.
2 issues found across 2 files
Confidence score: 3/5
packages/docs/v4/integrations/mastra.mdxdocuments an OpenAI credential while the model string routes through Mastra’s gateway, so users may see authentication failures or requests sent through the wrong provider—importopenaifrom@ai-sdk/openaiand install it, or document the required gateway credential.packages/docs/v4/integrations/mastra.mdxuses a fixed client ID, allowing multiple clients in one process to reuse or disconnect each other and terminate MCP/browser sessions—generate a unique ID for each client.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/docs/v4/integrations/mastra.mdx">
<violation number="1" location="packages/docs/v4/integrations/mastra.mdx:40">
P2: When an application creates multiple clients in one process, this fixed ID lets `@mastra/mcp` reuse or disconnect another client, terminating its MCP/browser session. Generate a unique ID for each client or explicitly share one singleton client.</violation>
<violation number="2" location="packages/docs/v4/integrations/mastra.mdx:56">
P1: With the documented OpenAI credential, this model string routes through Mastra’s gateway instead of the OpenAI provider. Import `openai` from `@ai-sdk/openai` and install it, or document the required gateway credential.</violation>
</file>
Architecture diagram
sequenceDiagram
participant User as User/Agent
participant Mastra as Mastra Agent
participant MCPClient as MCPClient (@mastra/mcp)
participant MCP as @browserbasehq/stagehand-mcp
participant Browserbase as Browserbase
participant Chrome as Local Chrome
Note over User,Chrome: Current State Architecture
User->>Mastra: generate("Open example.com...")
Mastra->>MCPClient: listTools()
MCPClient->>MCP: Spawn process (npx -y @browserbasehq/stagehand-mcp@0.1.0)
Note over MCPClient,MCP: stdio transport (MCP protocol)
MCP-->>MCPClient: Run, Snapshot, Screenshot tools
MCPClient-->>Mastra: Tool list
Mastra->>MCP: run(url="https://example.com")
alt BROWSERBASE_API_KEY set
MCP->>Browserbase: Remote browser session
Browserbase-->>MCP: Page snapshot
else Local Chrome
MCP->>Chrome: Local browser session
Chrome-->>MCP: Page snapshot
end
MCP-->>Mastra: Result content
Mastra->>MCP: snapshot()
MCP-->>Mastra: Page state
Mastra->>MCP: screenshot()
MCP-->>Mastra: Screenshot JPEG
Mastra-->>User: Final response
Note over Mastra,MCP: Connection stays open through agent run
Mastra->>MCPClient: disconnect()
MCPClient->>MCP: Shutdown / kill process
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| 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", |
Contributor
There was a problem hiding this comment.
P1: With the documented OpenAI credential, this model string routes through Mastra’s gateway instead of the OpenAI provider. Import openai from @ai-sdk/openai and install it, or document the required gateway credential.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/mastra.mdx, line 56:
<comment>With the documented OpenAI credential, this model string routes through Mastra’s gateway instead of the OpenAI provider. Import `openai` from `@ai-sdk/openai` and install it, or document the required gateway credential.</comment>
<file context>
@@ -6,17 +6,75 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st
+ 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,
+ });
</file context>
| ), | ||
| ); | ||
| const client = new MCPClient({ | ||
| id: "stagehand-browser", |
Contributor
There was a problem hiding this comment.
P2: When an application creates multiple clients in one process, this fixed ID lets @mastra/mcp reuse or disconnect another client, terminating its MCP/browser session. Generate a unique ID for each client or explicitly share one singleton client.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/mastra.mdx, line 40:
<comment>When an application creates multiple clients in one process, this fixed ID lets `@mastra/mcp` reuse or disconnect another client, terminating its MCP/browser session. Generate a unique ID for each client or explicitly share one singleton client.</comment>
<file context>
@@ -6,17 +6,75 @@ description: "Give a Mastra agent persistent Stagehand browser tools over MCP/st
+ ),
+);
+const client = new MCPClient({
+ id: "stagehand-browser",
+ servers: {
+ stagehand: {
</file context>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Mastra integration already has a supported host tool API: MCPClient. Lead the public guide with that integration route and a portable configuration for an existing application, instead of requiring a full Stagehand checkout.
This is an SDK/MCP integration, not a separate marketplace plugin. The source example remains available.
Stacked on #2971 for the shared
@browserbasehq/stagehand-mcppackage. The first 0.1.0 release is required before the portable npm command is available; the guide explicitly identifies this prerequisite.E2E Test Matrix
Documentation validation: a combined snapshot of all nine updated integration guides passed
mint validateandmint broken-links --check-anchors --check-redirects --check-snippets.