Support Local MCP Connections (#1049)

# why
To allow support for non-hosted MCP servers

# what changed
Added the option to connect over StdioClientTransport to an MCP server.
Users can define their connection in the common format:
```TypeScript
  const notionClient = await connectToMCPServer({
    command: "npx",
    args: ["-y", "@notionhq/notion-mcp-server"],
    env: {
      NOTION_TOKEN: process.env.NOTION_TOKEN,
    },
  });
```

- Added docs examples

# test plan

Author: miguelg719

.changeset/nasty-buckets-push.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Support local MCP server connections

.prettierignore

@@ -1,4 +1,5 @@
 pnpm-lock.yaml
 README.md
 **/*.json
-docs/
+docs/
+.github/

docs/best-practices/mcp-integrations.mdx

@@ -18,6 +18,10 @@ There are two options for connecting to MCP servers:
 1. **Pass a URL directly** - The simplest approach for quick setup
 2. **Create a connection first** - Gives you more control over the connection
 
+<Note>
+MCP client support is currently only available in TypeScript.
+</Note>
+
 ## Passing a URL
 
 The simplest way to add MCP integrations is by providing server URLs directly in the agent configuration:
@@ -50,12 +54,21 @@ const supabaseClient = await connectToMCPServer(
   `https://server.smithery.ai/@supabase-community/supabase-mcp/mcp?api_key=${process.env.SMITHERY_API_KEY}`
 );
 
+// You can also pass the config to start a local MCP server
+const notionClient = await connectToMCPServer({
+  command: "npx",
+  args: ["-y", "@notionhq/notion-mcp-server"],
+  env: {
+    NOTION_TOKEN: process.env.NOTION_TOKEN,
+  },
+});
+
 // Use the connected client
 const agent = stagehand.agent({
   provider: "openai", 
   model: "computer-use-preview",
-  integrations: [supabaseClient],
-  instructions: `You can interact with Supabase databases. Use these tools to store and retrieve data.`,
+  integrations: [supabaseClient, notionClient],
+  instructions: `You can interact with Supabase databases and Notion. Use these tools to store and retrieve data.`,
   options: {
     apiKey: process.env.OPENAI_API_KEY,
   },

lib/mcp/connection.ts

@@ -3,32 +3,49 @@ import {
   ClientOptions,
 } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { MCPConnectionError } from "../../types/stagehandErrors";
 
 export interface ConnectToMCPServerOptions {
   serverUrl: string | URL;
   clientOptions?: ClientOptions;
 }
 
+export interface StdioServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
 export const connectToMCPServer = async (
-  serverUrlOrOptions: string | ConnectToMCPServerOptions,
+  serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions,
 ): Promise<Client> => {
-  // Handle both string URL and options object
-  const options: ConnectToMCPServerOptions =
-    typeof serverUrlOrOptions === "string"
-      ? { serverUrl: serverUrlOrOptions }
-      : serverUrlOrOptions;
+  try {
+    let transport;
+    let clientOptions: ClientOptions | undefined;
 
-  const serverUrl = options.serverUrl.toString();
+    // Check if it's a stdio config (has 'command' property)
+    if (typeof serverConfig === "object" && "command" in serverConfig) {
+      transport = new StdioClientTransport(serverConfig);
+    } else {
+      // Handle URL-based connection
+      let serverUrl: string | URL;
+
+      if (typeof serverConfig === "string" || serverConfig instanceof URL) {
+        serverUrl = serverConfig;
+      } else {
+        serverUrl = (serverConfig as ConnectToMCPServerOptions).serverUrl;
+        clientOptions = (serverConfig as ConnectToMCPServerOptions)
+          .clientOptions;
+      }
+
+      transport = new StreamableHTTPClientTransport(new URL(serverUrl));
+    }
 
-  try {
-    const transport = new StreamableHTTPClientTransport(
-      new URL(options.serverUrl),
-    );
     const client = new Client({
       name: "Stagehand",
       version: "1.0.0",
-      ...options.clientOptions,
+      ...clientOptions,
     });
 
     await client.connect(transport);
@@ -37,7 +54,7 @@ export const connectToMCPServer = async (
       await client.ping();
     } catch (pingError) {
       await client.close();
-      throw new MCPConnectionError(serverUrl, pingError);
+      throw new MCPConnectionError(serverConfig.toString(), pingError);
     }
 
     return client;
@@ -46,6 +63,6 @@ export const connectToMCPServer = async (
     if (error instanceof MCPConnectionError) {
       throw error; // Re-throw our custom error
     }
-    throw new MCPConnectionError(serverUrl, error);
+    throw new MCPConnectionError(serverConfig.toString(), error);
   }
 };