[STG-1837] Document MCP start sessionId support

[monadoid]

why

The v3 MCP docs now need to describe the hosted server behavior where start can attach to an existing Browserbase session via an optional sessionId.

what changed

• Updated the MCP setup and tools docs to document optional start.sessionId.
• Clarified that omitting sessionId creates a new Browserbase session.
• Added a patch changeset for @browserbasehq/stagehand-docs.

test plan

• pnpm exec prettier --check packages/docs/v3/integrations/mcp/setup.mdx packages/docs/v3/integrations/mcp/tools.mdx

---

Summary by cubic

Added docs for optional sessionId on MCP start to attach to an existing Browserbase session; omitting it creates a new session. Addresses STG-1837 and publishes a patch to @browserbasehq/stagehand-docs.

^{Written for commit edc7cbd. Summary will update on new commits. Review in cubic}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
stagehand	🟢 Ready	View Preview	Apr 21, 2026, 8:21 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[changeset-bot]

🦋 Changeset detected

Latest commit: edc7cbd

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

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/stagehand-docs	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 3 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant Host as MCP Host (e.g. Claude)
    participant MCP as Stagehand MCP Server
    participant BB as Browserbase Platform

    Note over Host, BB: MCP Session Initialization Flow

    Host->>MCP: callTool("start", { sessionId? })
    
    alt NEW: sessionId is provided
        MCP->>BB: CHANGED: Attach to existing session (sessionId)
        BB-->>MCP: Session Context
    else sessionId is omitted
        MCP->>BB: Create new session
        BB-->>MCP: New Session ID & Context
    end

    MCP->>MCP: Set session as active for current transport
    
    Note right of MCP: Active session is used for<br/>future calls (navigate, act, etc.)

    MCP-->>Host: return { sessionId }

Loading