[STG-2405] fix: agent({ integrations }) with an MCP Client throws circular-structure JSON

[shrey150]

What & why

stagehand.agent({ integrations }) is unusable with a local/stdio MCP server. agent() logs its config as auxiliary metadata via JSON.stringify(options.integrations), but an MCP Client instance (what connectToMCPServer({ command, args }) returns) is a circular object — so the call throws TypeError: Converting circular structure to JSON before the agent ever runs.

This blocks the documented stdio-MCP path entirely (URL-string integrations are unaffected, since a string serializes fine).

The fix

packages/core/lib/v3/v3.ts — in the agent-creation log, serialize a safe descriptor instead of the raw array: keep URL strings, summarize Client instances as "[mcp client]". One site; it runs for all agent modes (dom/hybrid/cua). No public API change. Patch changeset added.

// before
value: JSON.stringify(options.integrations),
// after
value: JSON.stringify(
  options.integrations.map((i) => (typeof i === "string" ? i : "[mcp client]")),
),

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
Before fix (published 3.6.0): agent({ integrations: [connectToMCPServer({command:"npx", args:[…filesystem MCP…]})] }) run on live Browserbase	TypeError: Converting circular structure to JSON … at V3.agent — crashes before the agent starts. Reproduced on a second MCP server (@modelcontextprotocol/server-everything) → not server-specific.	Proves the bug and that it's general to any Client integration.
After fix (local build copied into a scratch project), same script on live Browserbase	exit 0, no circular error; agent connected to the MCP server (Secure MCP Filesystem Server running on stdio) and invoked its tools (got a real tool response).	Proves the fix unblocks agent({ integrations: [client] }) end-to-end.
pnpm build:esm (core) + grep built v3.js	build exit 0; built output contains the safe descriptor, no JSON.stringify(options.integrations).	Fix compiles and is present in the artifact under test.

Note: server-side ingestion is irrelevant here — this is a pure client-side serialization crash; the matrix exercises the exact throwing call path before and after.

Closes STG-2405.

🤖 Generated with Claude Code

---

Summary by cubic

Fixes a circular-JSON crash when creating an agent with MCP Client integrations (e.g., from connectToMCPServer). We now log a safe descriptor for integrations, so agent({ integrations: [client] }) works with local/stdio MCP servers across all modes. Addresses STG-2405.

^{Written for commit 01323a5. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 01323a5

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch

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

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User as User Code
    participant V3 as V3.agent()
    participant JSON as JSON.stringify
    participant Integrations as Integrations Array
    participant Log as Auxiliary Metadata Log

    User->>V3: agent({ integrations: [mcpClient] })
    V3->>V3: Prepare metadata object (includes integrations key)

    alt BEFORE FIX (circular crash)
        V3->>JSON: JSON.stringify(options.integrations)
        JSON->>Integrations: Attempt to serialize MCP Client
        Integrations-->>JSON: Circular reference
        JSON-->>V3: TypeError: Converting circular structure to JSON
        Note over V3: Agent never starts – throws
    else AFTER FIX (safe descriptor)
        V3->>V3: Map each integration: <br/>string? keep as-is, Client? → "[mcp client]"
        V3->>JSON: JSON.stringify(mappedIntegrations)
        JSON-->>V3: Safe string
        V3->>Log: Log metadata with safe integrations string
        Log-->>V3: OK
        V3-->>User: Agent created successfully
    end

Loading

_{Re-trigger cubic}