How to integrate Browserbase tool MCP with Mastra AI

Connect Mastra AI to Browserbase tool MCP. Start a new headless browser session now, download all artifacts from last session, and more using natural language, with authentication handled for you.

Browserbase tool logoBrowserbase tool
Api Key

Browserbase is a serverless platform for running and managing headless browsers at scale. It lets you automate and monitor browser tasks with Playwright, Puppeteer, and Selenium—no infrastructure headaches.

64 Tools

Introduction

This guide walks you through connecting Browserbase tool to Mastra AI using the Composio tool router. By the end, you'll have a working Browserbase tool agent that can create and manage browser sessions, run Browserbase agents, invoke functions, fetch pages, and download session replays and logs through natural language commands.

This guide will help you understand how to give your Mastra AI agent real control over a Browserbase tool account through Composio's Browserbase tool MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

For exact tool slugs and parameter tables, see the tool catalog in the Composio docs.

Also integrate Browserbase tool with

TL;DR

Here's what you'll learn:
  • Set up your environment so Mastra, OpenAI, and Composio work together
  • Create a Tool Router session in Composio that exposes Browserbase tool tools
  • Connect Mastra's MCP client to the Composio generated MCP URL
  • Fetch Browserbase tool tool definitions and attach them as a toolset
  • Build a Mastra agent that can reason, call tools, and return structured results
  • Run an interactive CLI where you can chat with your Browserbase tool agent

What is Mastra AI?

Mastra AI is a TypeScript framework for building AI agents with tool support. It provides a clean API for creating agents that can use external services through MCP.

Key features include:

  • MCP Client: Built-in support for Model Context Protocol servers
  • Toolsets: Organize tools into logical groups
  • Step Callbacks: Monitor and debug agent execution
  • OpenAI Integration: Works with OpenAI models via @ai-sdk/openai

What is the Browserbase tool MCP server, and what's possible with it?

The Browserbase MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Browserbase account. It provides structured and secure access to your browser sessions, contexts, projects, recordings, logs, files, and extensions, so your agent can create sessions, manage reusable contexts, inspect browser activity, retrieve recordings, and monitor project usage on your behalf.

  • Browser session management: Have your agent create isolated browser sessions, check their status, list recent sessions, and release running sessions when work is complete.
  • Reusable browser contexts: Let the agent create, inspect, and update browser contexts that preserve settings across multiple sessions.
  • Session monitoring and debugging: Direct your agent to retrieve live debugging access, review captured network activity, and inspect session logs.
  • Recordings and session artifacts: Instruct your agent to retrieve session replays, request downloadable recordings, and download generated session files.
  • Projects, files, and extensions: Have your agent review projects and usage, upload files for browser forms, and upload or inspect browser extensions.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Node.js 18 or higher
  • A Composio account with an active API key
  • An OpenAI API key
  • Basic familiarity with TypeScript
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key.
  • You need credits or a connected billing setup to use the models.
  • Store the key somewhere safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Go to Settings and copy your API key.
  • This key lets your Mastra agent talk to Composio and reach Browserbase tool through MCP.
3

Install dependencies

bash
npm install @composio/core @mastra/core @mastra/mcp @ai-sdk/openai dotenv

Install the required packages.

What's happening:

  • @composio/core is the Composio SDK for creating MCP sessions
  • @mastra/core provides the Agent class
  • @mastra/mcp is Mastra's MCP client
  • @ai-sdk/openai is the model wrapper for OpenAI
  • dotenv loads environment variables from .env
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key_here

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your requests to Composio
  • COMPOSIO_USER_ID tells Composio which user this session belongs to
  • OPENAI_API_KEY lets the Mastra agent call OpenAI models
5

Import libraries and validate environment

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey as string,
});
What's happening:
  • dotenv/config auto loads your .env so process.env.* is available
  • openai gives you a Mastra compatible model wrapper
  • Agent is the Mastra agent that will call tools and produce answers
  • MCPClient connects Mastra to your Composio MCP server
  • Composio is used to create a Tool Router session
6

Create a Tool Router session for Browserbase tool

typescript
async function main() {
  const session = await composio.create(
    composioUserID as string,
    {
      toolkits: ["browserbase_tool"],
    },
  );

  const composioMCPUrl = session.mcp.url;
  console.log("Browserbase tool MCP URL:", composioMCPUrl);
What's happening:
  • create spins up a short-lived MCP HTTP endpoint for this user
  • The toolkits array contains "browserbase_tool" for Browserbase tool access
  • session.mcp.url is the MCP URL that Mastra's MCPClient will connect to
7

Configure Mastra MCP client and fetch tools

typescript
const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      nasdaq: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

console.log("Fetching MCP tools from Composio...");
const composioTools = await mcpClient.getTools();
console.log("Number of tools:", Object.keys(composioTools).length);
What's happening:
  • MCPClient takes an id for this client and a list of MCP servers
  • The headers property includes the x-api-key for authentication
  • getTools fetches the tool definitions exposed by the Browserbase tool toolkit
8

Create the Mastra agent

typescript
const agent = new Agent({
    name: "browserbase_tool-mastra-agent",
    instructions: "You are an AI agent with Browserbase tool tools via Composio.",
    model: "openai/gpt-5",
  });
What's happening:
  • Agent is the core Mastra agent
  • name is just an identifier for logging and debugging
  • instructions guide the agent to use tools instead of only answering in natural language
  • model uses openai("gpt-5") to configure the underlying LLM
9

Set up interactive chat interface

typescript
let messages: AiMessageType[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end.\n");

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: "> ",
});

rl.prompt();

rl.on("line", async (userInput: string) => {
  const trimmedInput = userInput.trim();

  if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
    console.log("\nGoodbye!");
    rl.close();
    process.exit(0);
  }

  if (!trimmedInput) {
    rl.prompt();
    return;
  }

  messages.push({
    id: crypto.randomUUID(),
    role: "user",
    content: trimmedInput,
  });

  console.log("\nAgent is thinking...\n");

  try {
    const response = await agent.generate(messages, {
      toolsets: {
        browserbase_tool: composioTools,
      },
      maxSteps: 8,
    });

    const { text } = response;

    if (text && text.trim().length > 0) {
      console.log(`Agent: ${text}\n`);
        messages.push({
          id: crypto.randomUUID(),
          role: "assistant",
          content: text,
        });
      }
    } catch (error) {
      console.error("\nError:", error);
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    console.log("\nSession ended.");
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});
What's happening:
  • messages keeps the full conversation history in Mastra's expected format
  • agent.generate runs the agent with conversation history and Browserbase tool toolsets
  • maxSteps limits how many tool calls the agent can take in a single run
  • onStepFinish is a hook that prints intermediate steps for debugging

Complete Code

Here's the complete code to get you started with Browserbase tool and Mastra AI:

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({ apiKey: composioAPIKey as string });

async function main() {
  const session = await composio.create(composioUserID as string, {
    toolkits: ["browserbase_tool"],
  });

  const composioMCPUrl = session.mcp.url;

  const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      browserbase_tool: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

  const composioTools = await mcpClient.getTools();

  const agent = new Agent({
    name: "browserbase_tool-mastra-agent",
    instructions: "You are an AI agent with Browserbase tool tools via Composio.",
    model: "openai/gpt-5",
  });

  let messages: AiMessageType[] = [];

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: "> ",
  });

  rl.prompt();

  rl.on("line", async (input: string) => {
    const trimmed = input.trim();
    if (["exit", "quit"].includes(trimmed.toLowerCase())) {
      rl.close();
      return;
    }

    messages.push({ id: crypto.randomUUID(), role: "user", content: trimmed });

    const { text } = await agent.generate(messages, {
      toolsets: { browserbase_tool: composioTools },
      maxSteps: 8,
    });

    if (text) {
      console.log(`Agent: ${text}\n`);
      messages.push({ id: crypto.randomUUID(), role: "assistant", content: text });
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main();

Conclusion

You've built a Mastra AI agent that can interact with Browserbase tool through Composio's Tool Router. You can extend this further by:
  • Adding other toolkits like Gmail, Slack, or GitHub
  • Building a web-based chat interface around this agent
  • Using multiple MCP endpoints to enable cross-app workflows
TOOLS

Supported Tools

Every Browserbase tool action and event your agent gets out of the box.

Attach Browserbase Function Secret

Attach an existing project secret to a Function by UUID.

Update Browser Context

Tool to update a specific browser context.

Create Browserbase Agent

Create a reusable browser agent with a name and optional system prompt and result schema.

Create Browser Context

Create a reusable browser context; the API key can select the project.

Create Browser Session

Create an isolated Browserbase session and return its connection details.

Create Browserbase Webhook

Register a publicly reachable HTTPS endpoint for project event deliveries.

Delete Browserbase Agent

Delete a reusable browser agent by its agentId.

Delete a browser context

Tool to delete a browser context and all its stored data (cookies, localStorage, etc.).

Delete Download

Delete a download file from storage and mark it as deleted.

Delete a browser extension

Tool to delete an uploaded browser extension by its ID.

Delete Session Downloads

Tool to delete all file downloads from a specific browser session.

Delete Browserbase Webhook

Delete a webhook, immediately stopping deliveries and retiring its secret.

Detach Browserbase Function Secret

Detach a project secret from a Function by UUID.

Download Session Artifacts

Download a completed session's generated files as a ZIP archive.

Fetch Browserbase Page

Fetch a page and return its content, headers, and metadata.

Get Browserbase Agent

Retrieve a reusable browser agent by its agentId.

Get Certificate

Retrieve a Browserbase certificate by its ID.

Get Browser Context

Return metadata for a browser context by ID.

Get Download

Get a single download by ID as metadata or a downloadable file object.

Retrieve a browser extension

Tool to retrieve details of a specific browser extension.

Get Browserbase Function

Retrieve a Browserbase function by its ID.

Get Browserbase Function Build

Retrieve a Browserbase function build by its build ID.

Get Browserbase Function Build Logs

Retrieve Browserbase function build logs by the build ID.

Get Browserbase Function Version

Retrieve a Browserbase function version by its version ID.

Get Browserbase Invocation

Retrieve a Browserbase function invocation by its invocation ID.

Get Browserbase Invocation Logs

Retrieve Browserbase function invocation logs by the invocation ID.

Get Browserbase Keypair

Retrieve the project's public HPKE encryption key and keypair ID.

Get Browserbase Project

Return project metadata, default timeout, and assigned concurrency.

Get project usage statistics

Tool to retrieve usage statistics for a project including browser minutes and proxy bytes consumed.

Get Browserbase Agent Run

Retrieve a browser agent run's current status, result, and session details.

Get Browserbase Secret

Retrieve a project secret's ID and name by UUID, without its secret value.

Get Browser Session

Return status, connection details, and timestamps for a browser session.

Get Session Debug URLs

Return live debugger and WebSocket URLs for a running browser session.

Get Session Logs

Return network request and response events captured during a browser session.

Get Session Replay

Return HLS replay metadata and page playlist paths for a recorded session.

Get Session Replay Page

Return the HLS M3U8 playlist for one recorded replay page.

Get Browserbase Webhook

Retrieve a single webhook by ID, without its signing secret.

Invoke Browserbase Function

Invoke a deployed Browserbase function asynchronously.

List Browserbase Agents

List one page of reusable browser agents across your account.

List Certificates

List Browserbase certificates with their IDs, timestamps, and project IDs.

List Browserbase Downloads

List one page of download metadata for a required browser session.

List Browserbase Function Builds

List one page of Browserbase function builds, optionally filtered by status.

List Browserbase Functions

List one page of Browserbase functions and the total number available.

List Browserbase Function Secrets

List one page of secret IDs and names attached to a Browserbase function, optionally filtered by creation time.

List Browserbase Function Versions

List one page of versions for a Browserbase function by its UUID.

List Browserbase Projects

List projects with their default timeout and assigned concurrency.

List Recording Downloads

Poll per-page MP4 assembly after requesting recording downloads until every page is COMPLETED or FAILED.

List Browserbase Run Messages

List a page of a browser agent run's messages, oldest first, with assistant or tool roles and text or typed content parts.

List Browserbase Agent Runs

List a page of browser agent runs across your account.

List Browserbase Secrets

List one page of project secret IDs and names, optionally filtered by creation time.

List Browser Sessions

List browser sessions, optionally filtered by status or user metadata.

List Browserbase Function Version Invocations

List one page of invocations for a Browserbase function version by its UUID.

List Browserbase Webhooks

List one page of the project's webhooks, newest first, without signing secrets.

Release Browser Session

Irreversibly request release of a running browser session, ending it before its configured timeout to avoid further charges.

Request Recording Downloads

Start asynchronous MP4 assembly for every recorded page of a completed session, then poll List Recording Downloads until every page is COMPLETED or FAILED.

Resume Browserbase Agent Run

Resume only a PAUSED browser agent run with optional additional input.

Run Browserbase Agent

Start a browser agent run to complete a task using web search and browser tools.

Stop Browserbase Agent Run

Request that an in-progress browser agent run stop.

Update Browserbase Agent

Update a reusable browser agent's name, system prompt, or result schema.

Update Browserbase Webhook

Update a webhook's delivery URL, subscribed event types, or both.

Upload Browser Extension

Tool to upload a browser extension for use in sessions.

Upload Session File

Upload one file so browser interactions can select it in a file input field.

Upload Session Files

Upload multiple files to one browser session for file-input interactions.

Web Search

Perform a web search and return structured results.

FAQ

Frequently asked questions

Start with Browserbase tool.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Browserbase tool tool your agent needs.Free to start.

Start building