feat: Supports request header authentication with connectToMCPServer

[huuyafwww]

why

Hello, thank you for developing the wonderful product Stagehand.
I am currently using Stagehand for my project.
It is very comfortable and convenient.
While developing, I was using connectToMCPServer to establish the client connection for agent integration settings,
and I discovered it does not support authentication via request headers (Authorization header).

In my project, I attempted to use DeepWiki's MCP server, which can connect to private repositories.
However, since it doesn't allow setting the API key via URL parameters like Supabase's MCP does,
I couldn't establish a connection using connectToMCPServer.
https://mcp.devin.ai/

Because the API key must be included in the Authorization request header,
I need to make modifications to handle such MCP servers in a more generic way.

what changed

We have modified connectToMCPServer to accept options for StreamableHTTPClientTransport as arguments.

test plan

• pnpm install and pnpm build, pnpm lint succeed
• Passed the tests in packages/core/tests/public-api/v3-core.test.ts

---

Summary by cubic

Adds request header authentication to connectToMCPServer by exposing requestOptions to the HTTP transport. This enables connecting to MCP servers that require Authorization headers (e.g., DeepWiki).

• New Features
  • connectToMCPServer now accepts requestOptions (StreamableHTTPClientTransportOptions) passed to StreamableHTTPClientTransport, allowing custom headers via requestInit.headers.
  • Updated docs with an Authorization header example; adjusted public API tests to include the new option; added a changeset to publish patch releases for core and docs.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 91d5e1c

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

This PR includes changesets to release 4 packages

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

[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 User as User Application
    participant Core as Stagehand Core (connectToMCPServer)
    participant SDK as MCP SDK Client
    participant Transport as StreamableHTTPClientTransport
    participant Server as Remote MCP Server (e.g. DeepWiki)

    Note over User,Server: NEW: HTTP Transport with Auth Headers

    User->>Core: connectToMCPServer(config)
    
    alt config is ConnectToMCPServerOptions
        Core->>Core: NEW: Extract requestOptions (headers, etc.)
        Core->>Transport: NEW: Instantiate with serverUrl and requestOptions
    else config is string/URL
        Core->>Transport: Instantiate with serverUrl only
    end

    Core->>SDK: Create Client with Transport
    Core->>SDK: client.connect()
    
    SDK->>Transport: start()
    
    Transport->>Server: NEW: HTTP Request with custom headers
    Note right of Transport: Headers include Authorization: Bearer <token>
    
    alt Connection Success
        Server-->>Transport: 200 OK / SSE Stream
        Transport-->>SDK: Connected
        SDK-->>Core: Client Instance
        Core-->>User: client
    else Connection Failure (Auth Error)
        Server-->>Transport: 401 Unauthorized
        Transport-->>SDK: Error
        SDK-->>Core: MCPConnectionError
        Core-->>User: throw MCPConnectionError
    end

Loading

[greptile-apps]

Greptile Summary

This PR adds support for HTTP request header authentication to connectToMCPServer, enabling connections to MCP servers that require authentication via headers (like Authorization) rather than URL parameters.

Key Changes:

• Added optional requestOptions parameter to ConnectToMCPServerOptions interface
• requestOptions is passed directly to StreamableHTTPClientTransport constructor
• Updated type tests to reflect new optional parameter
• Documentation includes clear example showing Authorization header usage

Issues Found:

• Error handling calls serverConfig.toString() on objects, which produces [object Object] instead of meaningful error messages. This affects lines 67 and 76 in connection.ts.

Confidence Score: 4/5

• This PR is mostly safe to merge with minor error handling improvements needed
• The implementation is straightforward and correctly passes through authentication options to the MCP SDK. However, error messages will be less helpful when objects are passed as serverConfig due to toString() issues on lines 67 and 76.
• Pay attention to packages/core/lib/v3/mcp/connection.ts - fix error message formatting for better debugging experience

Important Files Changed

Filename	Overview
packages/core/lib/v3/mcp/connection.ts	Adds requestOptions parameter to support authentication headers. Error handling has issues with object stringification.
packages/core/tests/public-api/v3-core.test.ts	Type test updated to include new requestOptions parameter. Changes are minimal and correct.
packages/docs/v3/best-practices/mcp-integrations.mdx	Documentation updated with clear example showing how to use request headers for authentication. Well-written.

Sequence Diagram

sequenceDiagram
    participant User
    participant connectToMCPServer
    participant StreamableHTTPClientTransport
    participant MCP Server

    User->>connectToMCPServer: Call with serverConfig
    alt serverConfig has requestOptions
        connectToMCPServer->>connectToMCPServer: Extract requestOptions
        connectToMCPServer->>StreamableHTTPClientTransport: new Transport(url, requestOptions)
        Note over StreamableHTTPClientTransport: requestOptions includes<br/>headers (e.g., Authorization)
    else no requestOptions
        connectToMCPServer->>StreamableHTTPClientTransport: new Transport(url)
    end
    connectToMCPServer->>MCP Server: client.connect(transport)
    MCP Server-->>connectToMCPServer: Connection established
    connectToMCPServer->>MCP Server: client.ping()
    MCP Server-->>connectToMCPServer: Ping response
    connectToMCPServer-->>User: Return connected client

Loading

_{Last reviewed commit: 2ee2589}

[greptile-apps]

_{3 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (2)

packages/core/lib/v3/mcp/connection.ts
When serverConfig is an object (like StdioServerConfig or ConnectToMCPServerOptions), toString() returns [object Object] instead of useful information

      throw new MCPConnectionError(typeof serverConfig === 'string' || serverConfig instanceof URL ? serverConfig.toString() : 'serverUrl' in serverConfig ? serverConfig.serverUrl.toString() : serverConfig.command, pingError);

---

packages/core/lib/v3/mcp/connection.ts
Same issue here - when serverConfig is an object, toString() returns [object Object]

    throw new MCPConnectionError(typeof serverConfig === 'string' || serverConfig instanceof URL ? serverConfig.toString() : 'serverUrl' in serverConfig ? serverConfig.serverUrl.toString() : serverConfig.command, error);

[huuyafwww]

merged
#1735