feat(claude-code): install Stagehand from a plugin marketplace

[shrey150]

Claude Code setup currently requires cloning and building Stagehand and copying MCP configuration. Add a Claude Code marketplace with a Stagehand plugin, so users can install it using /plugin marketplace add browserbase/stagehand and /plugin install stagehand@browserbase-stagehand.

The plugin runs @browserbasehq/stagehand-mcp@0.1.0, a small public package that bundles the existing Core stdio server. Core stays private; the SDK stays external to preserve its browser extension assets. Includes release wiring, the plugin manifest, marketplace catalog, README, and public guide. The Agent SDK source example remains available for application developers.

Release prerequisite: configure npm trusted publishing for @browserbasehq/stagehand-mcp from browserbase/stagehand / .github/workflows/release.yml, then publish the included 0.1.0 changeset. The docs identify this gate; the marketplace command cannot start the server until that release exists. This package also supports the separately reviewed Codex and framework integrations.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
claude plugin validate for plugin and marketplace	Passed (marketplace has an optional-description warning)	Official manifest/schema validation
MCP build and pack	Self-contained server emitted and packed	Core bundled; public runtime dependencies preserved
Clean consumer MCP handshake	run, snapshot, screenshot listed	Packed package loads independently of the monorepo
Packed server against Browserbase / example.com	Correct title, persistent snapshot state, JPEG returned; transport closed	Actual browser behavior through the published artifact shape
Release helper tests	17 tests passed	Release validation/changelog helpers

No npm publish or public marketplace listing was performed. Claude’s complete model loop and the post-publication npx download are not claimed as tested.

Documentation validation: a combined snapshot of all nine updated integration guides passed mint validate and mint broken-links --check-anchors --check-redirects --check-snippets.

[mintlify]

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

Project	Status	Preview	Updated
stagehand	🟢 Ready	View Preview	Sep 17, 2026, 10:33 PM

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

[changeset-bot]

🦋 Changeset detected

Latest commit: c8c4321

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-mcp	Minor

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]

All reported issues were addressed across 16 files

Architecture diagram

sequenceDiagram
    participant User as Claude Code User
    participant CC as Claude Code CLI
    participant Mkt as Plugin Marketplace (browserbase/stagehand)
    participant Plugin as Stagehand Plugin (.mcp.json)
    participant NPM as npm Registry
    participant MCP as @browserbasehq/stagehand-mcp<br/>(bundled Core stdio server)
    participant SDK as Stagehand SDK (external)
    participant Browser as Chrome/Browserbase

    Note over User,Browser: NEW: Claude Code Marketplace Installation Flow

    User->>CC: /plugin marketplace add browserbase/stagehand
    CC->>Mkt: Fetch marketplace.json (browserbase/stagehand repo)
    Mkt-->>CC: Return plugin metadata (stagehand v0.1.0)
    CC->>Mkt: /plugin install stagehand@browserbase-stagehand
    Mkt-->>CC: Resolve plugin source (./packages/integrations/claude-code/plugin)
    CC->>CC: Register plugin + parse .mcp.json
    CC->>NPM: npx -y @browserbasehq/stagehand-mcp@0.1.0
    alt Package published
        NPM-->>CC: Download package (dist/server.mjs + deps)
        CC->>MCP: Spawn server process (stdio)
        MCP->>MCP: Initialize facade server (browser state persists)
        MCP->>SDK: Load Stagehand SDK (external, keeps extension assets)
        SDK-->>MCP: Ready
        MCP-->>CC: MCP handshake (tools: run, snapshot, screenshot)
        User->>CC: Use /mcp or Claude agent tools
        CC->>MCP: Call tool (run/snapshot/screenshot)
        MCP->>SDK: Operate browser
        SDK->>Browser: Browser actions
        Browser-->>SDK: Page state/result
        SDK-->>MCP: Return data
        MCP-->>CC: Tool result
    else Package not yet published (pre-release gate)
        NPM-->>CC: 404 / package not found
        CC-->>User: Error: server cannot start
        Note over User,NPM: Requires npm trusted publishing +<br/>changeset release to be completed first
    end

    Note over User,MCP: Alternative: Source-based workflow (unchanged, for app developers)
    User->>CC: Build packages/integrations/core from source
    CC->>MCP: node packages/integrations/mcp/dist/server.mjs (local dev)

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>