How to connect a BambooHR MCP with Claude Code (4 steps)

Developers building people ops automations or internal tooling that surfaces HR data have to manage per-company API keys, handle BambooHR's custom field model, and write one-off integrations every time a new workflow needs a different slice of employee data.

To help your developers query employee records, track time off, and surface org data more easily from the terminal, we'll show you how to connect BambooHR with Merge Agent Handler's BambooHR MCP server.

How it works

Merge Agent Handler connects Claude Code to the BambooHR API through a single CLI setup.

You install the Merge CLI, authenticate once with your Merge Agent Handler account, and register the connection with one command.

Merge handles BambooHR API credentials on your behalf, so you never store a company API key locally or manage it across environments.

Here's the command that registers the connection:

merge setup claude-code

Related: How to use a BambooHR MCP in Codex

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Claude Code installed (run claude --version to confirm)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A BambooHR account with API access enabled (Admin access required to generate an API key)

If you want to connect Merge Agent Handler's BambooHR MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install with pipx: pipx install merge-api

Then verify the installation: merge --version

2. Configure the CLI and log in

Run merge login to connect the CLI to your Merge account: merge login

This starts an authenticated session so the CLI can make requests on your behalf.

Related: How to integrate a BambooHR MCP with Cursor

3. Add Agent Handler to Claude Code

The simplest way to register Agent Handler with Claude Code:

merge setup claude-code

Alternatively, register manually:

claude mcp add 
--transport http agent-handler https://ah-api.merge.dev/mcp

Open Claude Code and run: /mcp

agent-handler should appear under Local MCPs with a connected status.

Related: How to use a HiBob MCP in Claude Code

4. Authenticate BambooHR

To confirm the connection is working, open a Claude Code session and try: "List all employees hired in the last 90 days, including their department, manager, and start date."

On first use, a Magic Link will appear to finish connector authentication.

You should then see an output like the following:

{{this-blog-only-cta}}

BambooHR MCP FAQ

In case you have more questions on setting up and using the BambooHR MCP in Claude Code, we've addressed several more commonly-asked questions below.

What can you do once the BambooHR MCP is connected to Claude Code?

With BambooHR connected, Claude Code can:

• Query employee records: retrieve employee profiles including job title, department, manager, location, and employment status across the full org or filtered to a specific team

• Track time off: pull PTO balances, approved time-off requests, and upcoming absences for individual employees or entire departments

• Surface org structure: retrieve reporting relationships and headcount by department, useful for planning agents that need current org data before generating summaries or recommendations

• Access job history: read employment history records including previous roles, promotions, and compensation changes for a given employee

• Pull custom fields: retrieve company-specific custom field data that HR teams have added to employee profiles, such as equipment assignments, certifications, or internal identifiers

• List new hires and terminations: query employees by hire date or status to power onboarding automation or offboarding checklists triggered by changes in employment status

Why use Merge Agent Handler vs. a self-hosted BambooHR MCP server?

You can build a self-hosted MCP server on top of BambooHR's API. The authentication model is straightforward for a single company: generate an API key from the BambooHR admin panel, pass it as a header, and start making requests. For a developer with one BambooHR account and a narrow use case, that's a workable starting point.

The problem is data sensitivity. BambooHR holds compensation records, performance review scores, and in some configurations personal identifiers that should never reach an agent indiscriminately.

A self-hosted setup has no mechanism for blocking sensitive fields at the tool level. An agent that needs headcount by department can also read salary data and custom fields containing personal information unless the MCP server is explicitly written to filter those fields out. And maintaining that filtering logic as BambooHR's custom field schema changes is an ongoing engineering cost.

BambooHR doesn't offer an official MCP server, so the only option beyond Merge is a community-built integration. Community servers vary in maintenance and have no enterprise support, audit logging, or access control layer.

Merge Agent Handler adds DLP controls that let you block or redact specific fields before they reach an agent.

A headcount reporting agent, for example, can get employee names, departments, and start dates. But it can never sees compensation data or custom fields containing personal identifiers unless those fields are explicitly included. Every tool call is also logged with the timestamps, tool names, and inputs.

Why connect BambooHR to Claude Code?

BambooHR is the system of record for people data: who works where, who reports to whom, who just joined, and who is about to leave. HR teams and the engineering teams that build on people ops data currently have to export CSVs, write scheduled queries, or build dedicated integrations every time a new workflow needs access to that data.

With the BambooHR MCP connected, Claude Code can query employee records, pull PTO balances, and surface org structure without leaving the terminal.

This matters most when BambooHR data needs to trigger or inform a downstream action: generating an onboarding checklist for a new hire, flagging departments where headcount has dropped below a threshold, or pulling the team roster for a project kickoff. Developers get direct access to live HR data without building and maintaining a separate BambooHR integration each time a new use case comes up.