Contrib/1690

[monadoid]

why

From 1690 shoutout @huuyafwww !

This enables agent to connect to MCP servers that require Authorization headers.

what changed

connectToMCPServer was modified to accept options for StreamableHTTPClientTransport as arguments.

test plan

A public api test was added

---

Note

Low Risk
Small additive API change that only affects MCP HTTP connection setup; minimal behavior change unless callers opt into requestOptions.

Overview
connectToMCPServer now accepts requestOptions and forwards them to StreamableHTTPClientTransport, enabling HTTP connections to MCP servers that require request-header auth (e.g., Authorization).

Updates the public API type test to include requestOptions, adds docs showing a header-authenticated connection example, and publishes patch changesets for @browserbasehq/stagehand and @browserbasehq/stagehand-docs.

^{Written by Cursor Bugbot for commit 657b7d5. This will update automatically on new commits. Configure here.}

---

Summary by cubic

Enable header-based auth for MCP HTTP connections. connectToMCPServer now accepts requestOptions and forwards them to StreamableHTTPClientTransport.

• New Features
  • Added requestOptions to connectToMCPServer for HTTP transports to pass headers like Authorization.
  • Updated docs with an authenticated MCP server example, expanded the public API type test, and limited the changeset bump to @browserbasehq/stagehand (docs package bump removed).

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 6cee1df

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

[greptile-apps]

Greptile Summary

Extends connectToMCPServer to accept requestOptions, enabling HTTP-based MCP connections with custom request headers like Authorization.

• Added optional requestOptions: StreamableHTTPClientTransportOptions parameter to ConnectToMCPServerOptions interface
• Extracts and forwards requestOptions to StreamableHTTPClientTransport constructor
• Updated public API type test to validate the new optional field
• Documentation includes working example with Authorization header for Deep Wiki MCP server
• Backward compatible - existing code continues to work without changes

Confidence Score: 5/5

• Safe to merge - clean additive change with proper typing and documentation
• The PR makes a simple, backward-compatible API extension that adds an optional parameter. The implementation correctly extracts and passes the requestOptions to the underlying SDK transport, the type definitions are updated, tests validate the public API surface, and documentation provides a clear usage example. No breaking changes or logical issues.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/mcp/connection.ts	Added optional requestOptions parameter to support custom HTTP headers like Authorization
packages/core/tests/unit/public-api/v3-core.test.ts	Updated type test to include new requestOptions field
packages/docs/v3/best-practices/mcp-integrations.mdx	Added documentation example showing header-based authentication with requestOptions
.changeset/tender-experts-obey.md	Changeset documenting the new request header authentication support

_{Last reviewed commit: 657b7d5}

[greptile-apps]

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

1 issue found across 4 files

Confidence score: 4/5

• Minor documentation inconsistency in packages/docs/v3/best-practices/mcp-integrations.mdx: systemPrompt doesn’t mention DeepWiki even though deepWikiClient was added, which could confuse readers following the example.
• Overall impact is limited to docs/example accuracy, so this looks safe to merge with minimal risk.
• Pay close attention to packages/docs/v3/best-practices/mcp-integrations.mdx - update the example prompt to include DeepWiki for consistency.

Prompt for AI agents (all 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/v3/best-practices/mcp-integrations.mdx">

<violation number="1" location="packages/docs/v3/best-practices/mcp-integrations.mdx:86">
P2: The `systemPrompt` was not updated to mention DeepWiki after adding `deepWikiClient` to the `integrations` array. This makes the documentation example inconsistent — readers following this example would configure an integration the agent isn't instructed to use. The docs' own best practices section emphasizes providing clear instructions about all available tools.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Dev as Developer / Client
    participant Conn as connectToMCPServer()
    participant Transport as StreamableHTTPClientTransport
    participant MCPClient as MCP Client (SDK)
    participant Server as Remote MCP Server

    Note over Dev,Server: MCP HTTP Connection Flow with Authentication

    Dev->>Conn: connectToMCPServer(config)
    Note right of Dev: NEW: config includes requestOptions<br/>(e.g., Authorization headers)

    alt HTTP Transport Path
        Conn->>Transport: NEW: constructor(url, requestOptions)
        Note over Transport: Stores custom headers/requestInit
        
        Conn->>MCPClient: new Client({ transport, clientOptions })
        Conn->>MCPClient: connect()
        
        MCPClient->>Transport: start()
        Transport->>Server: CHANGED: HTTP Request (includes custom headers)
        
        alt Success
            Server-->>Transport: 200 OK / Stream
            Transport-->>MCPClient: Connection established
            MCPClient-->>Conn: client instance
            Conn-->>Dev: Return MCP Client
        else Unauthorized / Error
            Server-->>Transport: 401 Unauthorized
            Transport-->>MCPClient: Connection failed
            MCPClient-->>Conn: throw Error
            Conn-->>Dev: throw MCPConnectionError
        end
    else Stdio Transport Path (Unchanged)
        Conn->>Conn: Use StdioClientTransport(command, args)
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[miguelg719]

good stuff @huuyafwww !