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:

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

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

Related: How to use the Workday MCP server in Claude Code

2. Configure the CLI and log in

Run the interactive setup: merge configure

This prompts you for your Merge API key and sets your default workspace preferences, linking the CLI to your Merge Agent Handler account.

Then log in: merge login

Once you log in, the CLI can make authorized API requests on your behalf going forward.

3. Add Agent Handler to Claude Code

Register the Agent Handler MCP server with Claude Code:

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.

4. Authenticate BambooHR

Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose BambooHR and complete the API key setup using your company subdomain and API key. Merge stores and manages the credentials going forward.

The first time you use a BambooHR tool in a Claude Code session, a Magic Link may appear to complete connector authentication, as shown below.

Once authenticated, you won't need to re-authenticate unless you revoke access.

To confirm the connector is accessible, open a Claude Code session and run a command like "List all employees hired in the last 90 days, including their department, manager, and start date."

You should 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.