How to integrate Bamboohr MCP with Mastra AI

BOOK A CALLGET STARTED FOR FREE
Framework Integration Gradient
Bamboohr Logo
Mastra AI Logo
divider

Introduction

This guide walks you through connecting Bamboohr to Mastra AI using the Composio tool router. By the end, you'll have a working Bamboohr agent that can add new dependent for employee john doe, update direct deposit details for sarah smith, log overtime hours for marketing team members, post interview feedback on jane roe's application through natural language commands.

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

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

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 Bamboohr tools
  • Connect Mastra's MCP client to the Composio generated MCP URL
  • Fetch Bamboohr 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 Bamboohr 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 Bamboohr MCP server, and what's possible with it?

The BambooHR MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your BambooHR account. It provides structured and secure access to your HR data, so your agent can perform actions like managing employee benefits, updating payroll records, tracking time, and assisting with applicant management on your behalf.

  • Employee benefits administration: Automatically enroll employees in benefit groups, create or update benefit records, and manage company-wide benefit offerings with ease.
  • Payroll and direct deposit management: Enable your agent to create paystubs, add unpaid pay periods, and update employee direct deposit information for seamless payroll processing.
  • Dependent and tax record updates: Empower your agent to add employee dependents and modify withholding details, keeping employee records accurate and compliant.
  • Time tracking automation: Let your agent log new time tracking records for employees, ensuring precise attendance and overtime data for reporting and payroll.
  • Applicant and recruitment collaboration: Allow your agent to post comments on applicant records, streamlining feedback and communication during the hiring process.

Supported Tools & Triggers

Tools
Add benefit group employee recordThis endpoint allows you to associate an employee with a specific benefit group in bamboohr for a defined period.
Create employee benefit entryCreates or updates an employee benefit in the bamboohr system.
Create employee dependent recordThis endpoint allows you to create a new dependent for an existing employee in the bamboohr system.
Modify employee withholding detailsThis endpoint updates an employee's withholding information for tax purposes in the bamboohr system.
Create employee direct deposit accountUpdates the direct deposit account information for a specific employee in the bamboohr system.
Post employee paystub detailsCreates a new employee pay stub in the bamboohr system.
Create employee unpaid paystubPosts unpaid pay stubs for a specific employee in the bamboohr system.
Create company benefitThis endpoint creates a new company benefit in bamboohr.
Add time tracking recordThis endpoint allows you to add a new time tracking record for an employee in the bamboohr system.
Post applicant commentThis endpoint allows you to post a comment on a specific application in bamboohr's applicant tracking system.
Update employee time off historyAdds a new time off history item to an employee's record in bamboohr.
Request employee time offThis endpoint allows you to add or update a time off request for a specific employee in bamboohr.
Store time tracking clock entriesThe "store time tracking clock entries" endpoint allows you to create or update multiple time tracking entries for employees in bamboohr.
Store hour entriesThis endpoint allows you to store or update multiple time tracking hour entries for employees in bamboohr.
Create new employeeCreates a new employee record in the bamboohr system.
Submit candidate applicationThis endpoint creates a new job application in the bamboohr applicant tracking system.
Post employee training recordThis endpoint allows you to create a new training record for a specific employee in the bamboohr system.
Create job opening postCreates a new job opening in the bamboohr applicant tracking system.
Add or update list field valuesAdds new values or updates existing values for a specific list field in the bamboohr system.
Update employee table rowThis endpoint allows you to update a specific row in an employee's table within bamboohr.
Employee clock in via taskidClocks in an employee in the bamboohr time tracking system, marking the start of their work period.
Post employee clock outThis endpoint clocks out an employee in the bamboohr time tracking system, marking the end of their working hours.
Post training category via domainCreates a new training category in the bamboohr system.
Post training object for a company domainCreates a new training type in the bamboohr system with specified attributes and settings.
Add webhook with monitoring fieldsThe addwebhook endpoint allows you to create a new webhook in bamboohr, enabling real-time notifications for specific employee data changes.
Adjust employee time off balanceThis endpoint allows you to adjust the time off balance for a specific employee in bamboohr.
Fetch goal alignment optionsRetrieves the available goal alignment options for a specific employee or the authenticated api user in bamboohr.
Approve timesheets with timestampThe approvetimesheets endpoint enables managers or authorized personnel to approve multiple employee timesheets in a single api call within the bamboohr time tracking system.
Approve timesheets for employees that are currently clocked inThis endpoint will approve all timesheets for employees that are currently clocked in.
Retrieve employee performance optionsRetrieves the list of employees with whom a specific employee's goals can be shared within bamboohr.
Check employee goal creation permissionThis endpoint checks whether a specific employee has the permission to create goals within the bamboohr performance management system.
Post application status updateUpdates the status of a specific application in the bamboohr applicant tracking system.
Update time off request statusThis endpoint updates the status of a specific time-off request in bamboohr.
Delete employee withholding by idDeletes a specific employee withholding record from the bamboohr system.
Delete employee direct deposit accountsDeletes a specific direct deposit account associated with an employee in the bamboohr system.
Delete employee unpaid pay stubThis endpoint deletes a specific unpaid pay stub for an employee in the bamboohr system.
Clock in employee with time and locationThis endpoint records a clock-in event for a specific employee in the bamboohr time tracking system.
Post employee clock out datetimeThis endpoint records the clock-out time for a specific employee in the bamboohr time tracking system.
Clock out employee with locationThe clockoutemployee endpoint allows you to record an employee's clock-out time and location in the bamboohr time tracking system.
Close employee goalThe closeemployeegoal endpoint allows you to mark a specific performance goal as completed or closed for an individual employee in bamboohr.
Create time tracking projectCreates a new time tracking project in bamboohr.
Add employee goalThis endpoint allows you to add a new goal for a specific employee in the bamboohr performance management system.
Add comment to employee goalThis endpoint allows you to post a comment on a specific employee's goal within the bamboohr performance management system.
Delete company benefit by idDeletes a specific company benefit from the bamboohr system.
Delete employee pay stub by idDeletes a specific employee pay stub from the bamboohr system.
Delete time tracking entryThe deletetimetrackingentry endpoint allows for the deletion of a specific time tracking entry from the bamboohr system.
Delete clock entry idsDeletes multiple clock entries from the bamboohr time tracking system.
Delete file by idDeletes a specific file from the bamboohr system for a given company.
Delete employee file by idDeletes a specific file associated with an employee in the bamboohr system.
Delete employee training recordDeletes a specific employee training record from the bamboohr system.
Delete employee goalThis endpoint deletes a specific goal associated with an employee in the bamboohr performance management system.
Delete employee goal commentDeletes a specific comment on an employee's performance goal in the bamboohr system.
Delete employee table rowThis endpoint deletes a specific row from an employee's table in bamboohr.
Delete clock entries via idsDeletes multiple clock entries from the bamboohr time tracking system.
Delete hour entries by idsDeletes multiple time tracking hour entries from the bamboohr system.
Delete training categoryDeletes a specific training category from the bamboohr system for a given company.
Delete training type by idDeletes a specific training type from the bamboohr system.
Delete webhook by idThe deletewebhook endpoint is used to remove a specific webhook from the bamboohr system.
Adjust time tracking hoursThis endpoint allows you to adjust existing time tracking records in bamboohr.
Edit Current Clock In EntryThis endpoint allows an employee to clock in and record their work start time in the bamboohr time tracking system.
Post employee table row updateUpdates a specific row in a custom table for an individual employee in bamboohr.
Calculate employee time offRetrieves the time off calculator information for a specific employee in bamboohr.
Get employee clock entriesRetrieves a specific clock entry for an employee from the bamboohr time tracking system.
Retrieve company benefit by idRetrieves detailed information about a specific company benefit offered by an organization using bamboohr.
Get employee daily entriesRetrieves a specific daily time tracking entry for an employee in bamboohr.
Get employee goal aggregateRetrieves aggregated performance data for a specific employee's goal within the bamboohr system.
Retrieve company benefitsRetrieves a comprehensive list of company-wide benefits offered by the organization as configured in bamboohr.
Retrieve company benefit typeRetrieves a list of company benefit types available in the specified bamboohr company account.
Retrieve employee benefit filtersRetrieves employee benefit information based on specified filters.
Retrieve meta fields for domainRetrieves metadata about available fields in the bamboohr api for a specific company.
Retrieve meta tables for companydomainRetrieves metadata information about the tables available in the bamboohr system for a specific company.
Retrieve user meta informationRetrieves metadata about users within a specific company's bamboohr instance.
Get whos out for companyRetrieves a list of employees who are currently out of office or on leave within your organization.
Aggregate employee goals by idRetrieves aggregated goal information for a specific employee within a company's bamboohr system.
Aggregate employee goalsRetrieves aggregated performance goal data for a specific employee within a company's bamboohr system.
Aggregate employee goalsRetrieves aggregated information about an employee's goals within the bamboohr performance management system.
Retrieve employee dependents by company domainRetrieves a list of dependents for all employees in the company.
Retrieve file by idRetrieves a specific employee file from the bamboohr system.
Retrieve employee file by idRetrieves a specific file associated with an employee from the bamboohr system.
Fetch employee photo by sizeRetrieves an employee's photo from the bamboohr system in a specified size.
Fetch employee withholding by idRetrieves the withholding information for a specific employee within a company's bamboohr system.
Retrieve employee direct deposit account by idRetrieves detailed information about a specific employee's direct deposit account within a bamboohr company instance.
Fetch employee pay stub by idRetrieves detailed pay stub information for a specific employee within a company's bamboohr system.
Retrieve employee unpaid pay stubs by idRetrieves the unpaid pay stubs for a specific employee within a company's bamboohr account.
Retrieve time tracking record by idRetrieves a specific time tracking record from bamboohr based on the provided company domain and record id.
Fetch application by idRetrieves detailed information about a specific job application from bamboohr's applicant tracking system.
Fetch applications by company domain pathRetrieves a list of applications submitted through the bamboohr applicant tracking system (ats).
Retrieve employee timesheet dataRetrieves a specific timesheet for a given employee within a bamboohr company environment.
Get benefit coverages by company domainRetrieves the benefit coverages information for employees within a specific company in bamboohr.
Get payroll deductions by idRetrieves detailed information about a specific payroll deduction by its id for a given company in bamboohr.
Retrieve all benefits deduction typesRetrieves a comprehensive list of all deduction types configured in the bamboohr system for a specific company.
List benefit group employeesRetrieves a list of employees associated with benefit groups within a specific bamboohr company instance.
Retrieve benefit group plan costsRetrieves the costs associated with benefit group plans for a specific company in bamboohr.
Retrieve benefit group plansRetrieves a list of benefit group plans for a specified company in bamboohr.
Fetch benefit groupsRetrieves a list of benefit groups for a specific company in bamboohr.
Retrieve benefit plan coverage dataRetrieves detailed information about benefit plan coverages for employees within a specific bamboohr company environment.
Retrieve employee plan by idRetrieves detailed information about a specific employee plan within a company's bamboohr system.
Retrieve benefit plans by company domainRetrieves a list of benefit plans available for the specified company in bamboohr.
Retrieve applicant location dataRetrieves a list of locations associated with the applicant tracking system for a specific bamboohr company account.
Fetch report by company domain and idRetrieves a specific report from the bamboohr system for a given company.
Retrieve meta listsRetrieves metadata about reference lists available in a company's bamboohr instance.
Get employee by idRetrieves detailed information for a specific employee within a company's bamboohr system.
Retrieve employee deduction detailsRetrieves detailed information about a specific employee deduction within a bamboohr company account.
Retrieve employee dependent by idRetrieves detailed information about a specific employee's dependent in bamboohr.
Fetch employee directoryRetrieves the employee directory for a specified bamboohr company.
Get employee project assignmentsRetrieves a list of projects assigned to a specific employee within a company's bamboohr account.
Get Employee Table RowsRetrieves specific table data for a given employee from a company's bamboohr instance.
Retrieve employee goal commentsRetrieves comments associated with a specific goal for a particular employee within a company's bamboohr environment.
Retrieve goals for employee performanceRetrieves the performance goals for a specific employee within a company's bamboohr account.
List employee goals filtersRetrieves the available filters for an employee's performance goals in bamboohr.
Retrieve employee goal filtersRetrieves the available filters for an employee's performance goals in bamboohr.
Fetch hiring leads for applicant trackingRetrieves a list of hiring leads from the bamboohr applicant tracking system (ats) for a specified company.
Fetch applicant tracking jobsRetrieves a list of job postings from the company's applicant tracking system (ats) in bamboohr.
Monitor webhook fieldsRetrieves a list of fields currently being monitored for webhook notifications in bamboohr.
Retrieve employee project assignmentsRetrieves a list of time tracking projects assigned to a specific employee within a bamboohr company environment.
Get changed employees by company domainRetrieves a list of employees whose records have been changed in the bamboohr system for a specific company.
Fetch employees changed for tableRetrieves information about changes made to a specific table in the bamboohr system for a given company.
Get webhooks for company domainRetrieves a list of all webhooks configured for a specific company in bamboohr.
Fetch applicant tracking statusesRetrieves a list of all applicant tracking statuses for a specific bamboohr company.
Get employee project tasksRetrieves a list of tasks assigned to a specific employee for a particular project within a company's bamboohr account.
Fetch time off policiesRetrieves metadata about time off policies for a specific company in the bamboohr system.
Get time off requestsRetrieves a list of time off requests for a specific company in the bamboohr system.
Retrieve time off typesRetrieves a list of available time off types for a specific company in bamboohr.
Retrieve timesheet entriesRetrieves timesheet entries for a specific company in bamboohr.
Retrieve timesheets using company domainRetrieves specific timesheet data from the bamboohr time tracking system.
Get webhook by idRetrieves detailed information about a specific webhook registered in the bamboohr system.
Retrieve webhook log by idRetrieves the log entries for a specific webhook in a company's bamboohr instance.
Check employee clockin statusRetrieves the current clock-in status for a specific employee within a company's bamboohr environment.
View company domain filesThe viewfile endpoint allows you to retrieve and view employee files stored in the bamboohr system.
View employee files by idThis endpoint allows you to view a specific file associated with an employee in the bamboohr system.
Retrieve employee training recordRetrieves the training record for a specific employee within a bamboohr company account.
Retrieve employee time off policiesRetrieves the time off policies applicable to a specific employee within a bamboohr company.
Get employee time off policiesRetrieves the time-off policies applicable to a specific employee within a bamboohr company account.
Access training categoryRetrieves all training categories for a specific company in bamboohr.
Fetch training types by domainRetrieves a list of training types configured in the company's bamboohr system.
Update employee table row infoThis endpoint updates a specific row in an employee's table within bamboohr.
Reopen employee goalReopens a previously closed or completed goal for a specific employee in the bamboohr performance management system.
Generate custom report for companyCreates a custom report in bamboohr with specified parameters.
Upload employee photo by idUpdates the photo for a specific employee in the bamboohr system.
Post clock entries for time trackingThe create clock entries endpoint allows you to add or update time tracking entries for employees in the bamboohr system.
Post daily time tracking entriesThe addorupdatedailytimeentries endpoint allows you to create new or update existing daily time entries for employees in the bamboohr time tracking system.
Update company benefit detailsUpdates an existing company benefit in the bamboohr system.
Update employee dependent detailsThe updateemployeedependent endpoint allows you to modify the information of an existing employee dependent in the bamboohr system.
Update company file detailsUpdates an existing company file in bamboohr, allowing modifications to the file's metadata such as name, category, and employee sharing permissions.
Update employee information via idUpdates an employee's basic information in the bamboohr system.
Update employee specific fileUpdates an existing file associated with a specific employee in the bamboohr system.
Update employee training recordThe updateemployeetrainingrecord endpoint allows you to update an existing training record for a specific employee in the bamboohr system.
Update employee goalUpdates an existing employee goal in the bamboohr system.
Update employee goal commentUpdates a specific comment on an employee's goal in bamboohr's performance management system.
Update employee goal progressUpdates the progress of a specific employee's goal in bamboohr.
Share employee goal with othersUpdates the list of employees with whom a specific performance goal is shared in bamboohr.
Update employee goal with milestonesThis endpoint updates an existing employee goal with milestones in the bamboohr performance management system.
Update employee table row by idUpdates a specific row in a table associated with an employee's record in bamboohr.
Update training categoryThis endpoint allows you to update the name of an existing training category in bamboohr.
Update training type by idUpdates an existing training type in the bamboohr system.
Update webhook for company domainUpdates an existing webhook configuration in bamboohr.
Upload file to company domainThis endpoint allows you to upload files to the bamboohr system for a specific company.
Upload employee fileThis endpoint allows you to upload a file to an employee's record in bamboohr.
Post company loginAuthenticates a user with the bamboohr system, initiating a session for subsequent api calls.

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

What is Tool Router?

Composio's Tool Router 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 Tool Router

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

How the Tool Router works

The Tool Router 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

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

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 Bamboohr through MCP.

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

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

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

Create a Tool Router session for Bamboohr

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

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

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

Create the Mastra agent

typescript
const agent = new Agent({
    name: "bamboohr-mastra-agent",
    instructions: "You are an AI agent with Bamboohr 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

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: {
        bamboohr: 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 Bamboohr 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 Bamboohr 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: ["bamboohr"],
  });

  const composioMCPUrl = session.mcp.url;

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

  const composioTools = await mcpClient.getTools();

  const agent = new Agent({
    name: "bamboohr-mastra-agent",
    instructions: "You are an AI agent with Bamboohr 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: { bamboohr: 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 Bamboohr 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

How to build Bamboohr MCP Agent with another framework

OpenAI Agents SDK

OpenAI Agents SDK

Use Bamboohr MCP with OpenAI Agents SDK

Claude Agent SDK

Claude Agent SDK

Use Bamboohr MCP with Claude Agent SDK

Google ADK

Google ADK

Use Bamboohr MCP with Google ADK

LangChain

LangChain

Use Bamboohr MCP with LangChain

Vercel AI SDK

Vercel AI SDK

Use Bamboohr MCP with Vercel AI SDK

LlamaIndex

LlamaIndex

Use Bamboohr MCP with LlamaIndex

CrewAI

CrewAI

Use Bamboohr MCP with CrewAI

FAQ

What are the differences in Tool Router MCP and Bamboohr MCP?

With a standalone Bamboohr MCP server, the agents and LLMs can only access a fixed set of Bamboohr tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Bamboohr and many other apps based on the task at hand, all through a single MCP endpoint.

Can I use Tool Router MCP with Mastra AI?

Yes, you can. Mastra AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Bamboohr tools.

Can I manage the permissions and scopes for Bamboohr while using Tool Router?

Yes, absolutely. You can configure which Bamboohr scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Bamboohr data and credentials are handled as safely as possible.

Used by agents from

Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai

Never worry about agent reliability

We handle tool reliability, observability, and security so you never have to second-guess an agent action.

Book a call↗Get started for free