How to connect a BambooHR MCP to Cursor (4 steps)

You write and reason about your code in Cursor.

But the moment you start building something that integrates with BambooHR, you need details that only live in the API's responses.

Which fields are standard aliases versus custom field IDs? What does a time-off request object actually return? How does a table like job info structure its rows?

Without the MCP connection, answering those means leaving the editor, authenticating against BambooHR's API separately, running test calls, and pasting responses back into the session where the integration code is being written.

To help your developers inspect BambooHR's data model and query real employee records without leaving Cursor, we'll show you how to connect BambooHR with Merge Agent Handler's BambooHR MCP server.

How it works

Merge Agent Handler connects Cursor to the BambooHR API through the Merge CLI.

You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a ## Merge CLI section to your project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach BambooHR.

Once connected, Merge stores and manages your BambooHR API key, so you never expose a company key in your environment or rotate it by hand.

Related: How to use the BambooHR MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• 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 the Merge CLI with pipx: pipx install merge-api

Verify your installation: merge --version

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your account so it can make authorized requests to BambooHR on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, safe to re-run if you need to reset.

Related: A guide to integrating a BambooHR MCP with Codex

4. Authenticate BambooHR

Open a Cursor chat in your project and try a prompt such as:

Fetch one employee record and show every field with its alias, including the custom fields, so I can map them before I write the sync.

The first time you invoke a BambooHR tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

BambooHR MCP FAQ

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

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

With BambooHR connected, Cursor can:

• Inspect the employee object before writing a parser: fetch a real record to see which fields BambooHR returns and how empty values appear, so the deserialization code you write matches the actual response

• Resolve field aliases versus custom field IDs before writing a mapping: pull the field list so the sync you write targets BambooHR's real aliases and numeric custom-field IDs instead of guessing from labels

• Check the time-off request shape before writing absence logic: retrieve a real request to see the type, date range, amount, and status fields so the code you write handles them correctly

• Inspect a table's row format before writing history logic: pull a table like job info or compensation to see how BambooHR returns a row per change before you write the code that reads it

• Confirm time-off type values before writing validation or enums: fetch the time-off types so your type definitions and validation match BambooHR's actual IDs

• Check a report's response before writing an ingestion parser: run a company report so the code that reads it matches the real columns and format

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

You can connect directly to BambooHR with your own integration on top of its API. For a single developer on one BambooHR account, that's workable: generate an API key from the admin panel, authenticate, and start making calls.

It gets harder once more than one person uses it or you're building across multiple HR systems.

A BambooHR API key carries that company's full access, so sharing it across agents or teammates means every agent operates with the same reach, with no way to restrict which operations a given agent can call. And a BambooHR-specific server only solves BambooHR. The moment a customer or internal team runs Workday or another HRIS instead, you're back to building and authenticating another integration.

Merge Agent Handler handles BambooHR authentication centrally and exposes the same tools across HR systems through one connection.

You define exactly which BambooHR operations each agent can call, so an agent that inspects employee structure for code generation can read it without reaching compensation data or write operations. Every call is also logged with the timestamp, tool, and inputs, so you have a full record of what each agent read or changed.

For teams writing code against employee data, that combination of scoped access and central logging is the foundation you want before agents touch real records.

Why connect BambooHR to Cursor?

BambooHR's API data, the field aliases, the custom field IDs, the time-off request shape, the row-per-change tables, isn't something you can accurately reconstruct from documentation alone.

These are real-response details: standard fields carry aliases that differ from their labels, custom fields use numeric IDs, and tables return a row for each change rather than a single value.

Connecting BambooHR to Cursor puts that discovery step inside the editor.

Can I use Merge Agent Handler's BambooHR MCP with my employees?

Yes, Agent Handler for Employees is built to help organizations provision, secure, and govern how employees connect AI tools like Cursor to systems like BambooHR.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which employee data an agent can reach by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return compensation or personal data before results reach the editor session

• User-level audit logging so security and IT teams can review which employee records were accessed, by which employee identity, and when

The result is that employees can use the BambooHR MCP to write syncs against the real field structure, build mappings grounded in actual field aliases, write validation tied to real time-off types, and more, while IT keeps centralized control over which employee data each agent can reach.