Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/observe.ts:44-75 (handler)

  Core handler function that performs the observation using Stagehand's page.observe() method. This is the primary execution logic for observing elements on the page.

  async function handleObserve(
    context: Context,
    params: ObserveInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const stagehand = await context.getStagehand();
  
        const observations = await stagehand.page.observe({
          instruction: params.instruction,
          returnAction: params.returnAction,
        });
  
        return {
          content: [
            {
              type: "text",
              text: `Observations: ${JSON.stringify(observations)}`,
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to observe: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/multiSession.ts:258-261 (registration)

  Registers the specific tool named "multi_browserbase_stagehand_observe_session" by creating a multi-session aware wrapper around the base observeTool.

  export const observeWithSessionTool = createMultiSessionAwareTool(observeTool, {
    namePrefix: "multi_",
    nameSuffix: "_session",
  });

• src/tools/multiSession.ts:22-80 (helper)

  Helper factory function that generates session-aware tools by extending the input schema with sessionId and wrapping the original handler to use a session-specific context.

  function createMultiSessionAwareTool<TInput extends InputType>(
    originalTool: Tool<TInput>,
    options: {
      namePrefix?: string;
      nameSuffix?: string;
    } = {},
  ): Tool<InputType> {
    const { namePrefix = "", nameSuffix = "_session" } = options;
  
    // Create new input schema that includes sessionId
    const originalSchema = originalTool.schema.inputSchema;
    let newInputSchema: z.ZodSchema;
  
    if (originalSchema instanceof z.ZodObject) {
      // If it's a ZodObject, we can spread its shape
      newInputSchema = z.object({
        sessionId: z.string().describe("The session ID to use"),
        ...originalSchema.shape,
      });
    } else {
      // For other schema types, create an intersection
      newInputSchema = z.intersection(
        z.object({ sessionId: z.string().describe("The session ID to use") }),
        originalSchema,
      );
    }
  
    return defineTool({
      capability: originalTool.capability,
      schema: {
        name: `${namePrefix}${originalTool.schema.name}${nameSuffix}`,
        description: `${originalTool.schema.description} (for a specific session)`,
        inputSchema: newInputSchema,
      },
      handle: async (
        context: Context,
        params: z.infer<typeof newInputSchema>,
      ): Promise<ToolResult> => {
        const { sessionId, ...originalParams } = params;
  
        // Get the session
        const session = stagehandStore.get(sessionId);
        if (!session) {
          throw new Error(`Session ${sessionId} not found`);
        }
  
        // Create a temporary context that points to the specific session
        const sessionContext = Object.create(context);
        sessionContext.currentSessionId =
          session.metadata?.bbSessionId || sessionId;
        sessionContext.getStagehand = async () => session.stagehand;
        sessionContext.getActivePage = async () => session.page;
        sessionContext.getActiveBrowser = async () => session.browser;
  
        // Call the original tool's handler with the session-specific context
        return originalTool.handle(sessionContext, originalParams);
      },
    });
  }

• src/tools/observe.ts:30-42 (schema)

  Input schema definition for the base observe tool, which is extended by adding sessionId for the multi-session variant.

  const observeSchema: ToolSchema<typeof ObserveInputSchema> = {
    name: "browserbase_stagehand_observe",
    description:
      "Observes and identifies specific interactive elements on the current web page that can be used for subsequent actions. " +
      "This tool is specifically designed for finding actionable (interactable) elements such as buttons, links, form fields, " +
      "dropdowns, checkboxes, and other UI components that you can interact with. Use this tool when you need to locate " +
      "elements before performing actions with the act tool. DO NOT use this tool for extracting text content or data - " +
      "use the extract tool instead for that purpose. The observe tool returns detailed information about the identified " +
      "elements including their properties, location, and interaction capabilities. This information can then be used " +
      "to craft precise actions. The more specific your observation instruction, the more accurate the element identification " +
      "will be. Think of this as your 'eyes' on the page to find exactly what you need to interact with.",
    inputSchema: ObserveInputSchema,
  };

• src/tools/index.ts:43-52 (registration)

  Main tools array that includes all multi-session tools (via multiSessionTools), making this tool available to the MCP server.

  export const TOOLS = [
    ...multiSessionTools,
    ...sessionTools,
    navigateTool,
    actTool,
    extractTool,
    observeTool,
    screenshotTool,
    getUrlTool,
  ];