MCP Server

Beta. BambooHR's MCP server and AI connectors are in a closed beta. Request access to join. Already in the beta? Share feedback anytime.

The BambooHR MCP server connects your BambooHR account to AI assistants through the Model Context Protocol. It's what powers the BambooHR Claude Connector and ChatGPT Connector, and it's the reference for developers and security reviewers who want to know exactly which tools exist and how access is enforced.

Server endpoint

https://{your-subdomain}.bamboohr.com/api/mcp

Replace {your-subdomain} with your BambooHR subdomain, the part before .bamboohr.com in your BambooHR URL. Each customer has their own endpoint, scoped to their account. The transport is streamable HTTP.

The server is hosted by BambooHR. There's nothing to install or run locally.

What it does

The server exposes 56 tools across eleven areas of BambooHR: employees and directory, fields and metadata, datasets, reports, time off, goals, goal comments, hiring, global employment, files, and utilities. We chose this set by looking at the jobs HR teams most often want help with, and we're adding more based on what customers ask for.

Of those 56 tools:

41 are read-only.
14 change data. Twelve are marked Write in the tables below, and two that delete data permanently are marked Delete.
1 is a utility that performs no data access at all.

Once connected, an AI assistant can answer questions about employees, time off, goals, and hiring in natural language; query reporting datasets and run saved reports; take actions on your behalf within your permissions; and combine BambooHR data with other tools the same client is connected to.

Before you connect, you need

An active BambooHR account.
The AI Connectors app enabled by a BambooHR admin in Settings, then Apps, with your access level included in the audience they selected. This gate applies to the Claude and ChatGPT connectors. We're extending it to cover MCP access more broadly, so plan on it applying to any client you connect.
Permission to access the data you want the assistant to see. The server enforces BambooHR's existing permissions and cannot grant access you don't already have.
An MCP client that can complete an OAuth authorization code flow.

Authentication

The server is a standards-compliant OAuth 2.0 protected resource. It publishes:

https://{your-subdomain}.bamboohr.com/.well-known/oauth-protected-resource/api/mcp
https://{your-subdomain}.bamboohr.com/.well-known/oauth-authorization-server

Clients use these to discover the authorization server, the supported scopes, and the token endpoint. Sign-in happens on BambooHR's own login screen, and the user is shown what's being requested and must approve it before any access is granted. Access tokens are valid for one hour and refresh automatically.

Connecting from Claude or ChatGPT

Use the Claude Connector or ChatGPT Connector pages. They walk through the setup, including the client credentials we issue to beta participants.

Connecting from another MCP client

During beta, client registration is manual. There is no dynamic client registration endpoint yet, so a client that can't accept a pre-configured client ID and secret can't connect today. If your client supports entering those values, the setup is the same as the Claude and ChatGPT steps: point it at the server endpoint and supply the credentials we issue you.

For exploratory or scripted access, you can also use an access token directly as a bearer token in the Authorization header. Tokens are valid for one hour and carry the permissions of the user who created them. See BambooHR's Getting Started documentation for how to obtain one.

Treat any token or client secret like a password. Don't paste them into untrusted tools and don't commit them to source control.

Access model

The server enforces BambooHR's permissions exactly. What you can do through an AI assistant matches what you can do signed into BambooHR directly.

HR admins typically have the widest access, and this is the experience we've optimized for first.
Managers can see and act on data for themselves and, depending on their access level, their direct reports.
Everyone can see and act on their own information, and can look up basic directory details about coworkers when the company publishes an employee directory.

Access follows the caller's access level, not their job title, and several areas are gated independently of the rest of an employee's record:

Time off balances require the Time Off view permission for the target employee. Being that person's manager does not grant it. A caller without it receives an explicit 403.
Hiring tools require access to ATS settings, which most managers don't have.
Saved reports are visible only to callers with report access. Two callers in the same company can see different numbers of reports, including none.
Datasets require elevated permissions of their own.

Partial results are silent

This is the most important thing to understand when building on this server.

Different endpoints handle insufficient permissions differently, and not all of them tell you:

get_employee omits fields the caller can't read, with no marker. An absent field may mean it wasn't requested or that it's not permitted.
list_employees returns unreadable field values as null and names them in a per-record _restrictedFields array.
list_employees also drops employees entirely when the caller can't read a field used in a filter or sort, to avoid leaking their existence. _restrictedFields stays empty, and meta.total reflects only the visible rows.
get_data_from_dataset_v2 returns every requested field but represents inaccessible values as empty and lists withheld field names per record.

In practice this means the same query can return a different count for two callers with no indication that anything was withheld. Treat an empty or short result as "nothing this caller can see," never as "nothing exists," and never as a permission error. A 403 means access was denied; a 200 with no rows does not.

Available tools

The tools currently available are listed below. Names are shown exactly as they appear in an MCP client. MCP tool names use underscores, as in get_employee; they may differ from the kebab-case operationId values shown in the public API reference.

If your client still displays older hyphenated names, refresh its available tools. Workspace-managed connectors may require an administrator to refresh the connector's tools. If tools remain unavailable or calls fail, reconnect the connector; if necessary, remove and add it again.

Employees and directory

Look up people, read their records, and update fields.

get_employees_directory deserves a note: it reads your company's published employee directory, so it's how an assistant answers "who is this person" or "what team are they on" for coworkers outside the caller's reporting line. It's governed by your directory sharing settings rather than by per-employee record permissions, which makes it the primary lookup tool for people who aren't admins.

Tool	What it does	Type
`get_employees_directory`	Look up basic details about coworkers from the published company directory	Read
`get_employee`	Get one employee's record, requesting specific fields	Read
`list_employees`	List, search, and filter the employee roster	Read
`get_employee_table_data`	Read an employee's historical tables, such as job or compensation history	Read
`update_employee`	Update fields on an employee record	Write

Fields and metadata

Discover what's configured in the account before querying it.

Tool	What it does	Type
`list_fields`	List every employee field in the account, including custom fields	Read
`list_list_fields`	List dropdown and multi-select fields with their options	Read
`list_tabular_fields`	List the account's tables and the fields in each	Read

Datasets

Build ad-hoc queries against BambooHR's reporting datasets. This is where conversational access is strongest, since a single query can answer questions no saved report covers.

Tool	What it does	Type
`list_datasets_v1_2`	List the datasets available to query	Read
`get_fields_from_dataset_v1_2`	List the fields in a dataset	Read
`get_field_options_v1_2`	Get valid filter values for one or more dataset fields	Read
`get_data_from_dataset_v2`	Run a filtered, sorted, paginated query against a dataset	Read

Reports

Run reports already built in BambooHR.

Tool	What it does	Type
`list_reports`	List the saved custom reports the caller can access	Read
`get_report_by_id`	Run a saved report and return its rows	Read

Time off

One of the highest-traffic areas in BambooHR.

Tool	What it does	Type
`list_whos_out`	See who's out and which company holidays fall in a date range	Read
`list_time_off_requests`	List time off requests in a date range, filtered by status, employee, or type	Read
`get_time_off_balance`	Get an employee's balances by category, as of any date	Read
`list_time_off_types`	List the company's time off types	Read
`list_time_off_policies`	List the company's time off policies	Read
`list_employee_time_off_policies_v1_1`	List the policies assigned to one employee	Read
`create_time_off_request`	Submit a time off request	Write
`update_time_off_request_status`	Approve, deny, or cancel a request	Write

Goals

Full lifecycle management for employee goals, including milestone-based goals. Goals are addressed per employee, so answering a question about a team means resolving the people first.

Tool	What it does	Type
`list_goals`	List an employee's goals, filtered by status	Read
`get_goal_aggregate`	Get one goal with its comments and alignment options	Read
`get_goals_aggregate_v1_2`	Get a goals dashboard for an employee, including milestone goals	Read
`get_goals_filters_v1_2`	Get goal counts by status for an employee	Read
`get_alignable_goal_options`	List goals available as alignment targets	Read
`create_goal`	Create a goal, with or without milestones	Write
`update_goal_v1_1`	Update a goal's details, and add or remove milestones	Write
`update_goal_progress`	Set percent complete on a goal without milestones	Write
`update_goal_milestone_progress`	Mark a milestone complete or incomplete	Write
`close_goal`	Close a goal	Write
`reopen_goal`	Reopen a closed goal	Write
`delete_goal`	Permanently delete a goal	Delete

Goal comments

Tool	What it does	Type
`list_goal_comments`	List comments on a goal, with edit and delete permissions per comment	Read
`create_goal_comment`	Add a comment to a goal	Write
`update_goal_comment`	Edit a goal comment	Write
`delete_goal_comment`	Delete a goal comment	Delete

Hiring

Pipeline questions without switching tools. All hiring tools require access to ATS settings.

Tool	What it does	Type
`get_job_summaries`	List job openings with applicant counts	Read
`get_applications`	List and filter job applications	Read
`get_application_details`	Get one application in full, including answers and status history	Read
`get_statuses`	List the applicant statuses configured for the company	Read
`create_application_comment`	Add a comment to an application	Write

Global employment

For companies that hire internationally through BambooHR's global employment offering. These tools return data only if your company uses it.

They're available through the MCP server but aren't part of BambooHR's public REST API, so you won't find matching endpoints in the API reference.

Tool	What it does	Type
`list_bhr_global_workers`	List the people your company employs through global employment	Read
`get_bhr_global_worker`	Get the employment setup for one globally employed person	Read
`list_remote_employments`	List employer of record employments and their status	Read
`get_remote_employment`	Get one employment in detail	Read
`list_remote_employment_onboarding_steps`	See which onboarding steps are still outstanding for a new hire	Read
`list_supported_countries`	List the countries you can hire in	Read
`get_remote_json_schema`	Get the information required to hire someone in a given country	Read
`get_remote_global_employment_pricing_summary`	Get a summary of current global employment costs	Read
`get_remote_contractor_eligibility_questionnaire_schema`	Get the questionnaire that determines contractor eligibility in a country	Read
`convert_remote_currency`	Convert an amount between currencies for offer and cost comparisons	Read

Files

Metadata listings only. These tools list what exists and who can see it; they don't return file contents.

Tool	What it does	Type
`list_employee_files`	List the files attached to an employee	Read
`list_company_files`	List company files and their categories	Read

Utilities

Tools that make an assistant more reliable rather than returning HR data.

Tool	What it does	Type
`calculate_date`	Timezone-aware date arithmetic on the server: differences, durations, tenure, and upcoming anniversaries	Utility

Language models are unreliable at date math, so calculate_date moves it server-side and returns both a formatted label and structured fields. More utilities are coming, including one that tells the assistant who the current user is and what they have permission to do, so it can choose the right tool the first time instead of guessing.

How a request works

The client sends an MCP tool call to https://{your-subdomain}.bamboohr.com/api/mcp with an OAuth access token.
The server authenticates the request and identifies the user.
It validates the request and checks that the user has permission to perform the action.
It calls the appropriate BambooHR API endpoints on the user's behalf.
It returns the result to the client in MCP format.

Current limitations

56 tools today. Not every BambooHR capability is exposed yet.
Manual client registration. There's no dynamic client registration endpoint, so clients without a pre-built BambooHR connector need credentials configured by hand.
One hour access tokens. Fine for OAuth clients that refresh automatically; manually created bearer tokens need to be replaced.
Goals are per employee. There's no company-wide goals query, so questions about a team require resolving its members first.
Some writes still go through BambooHR. Changes that require approvals or workflows follow BambooHR's existing flows rather than completing immediately.
Partial results are not always signposted. See Partial results are silent.

What's next

More tools across additional areas of BambooHR
Easier setup from any MCP client, without hand-configured credentials
More utility tools, starting with user context
Broader admin control over MCP access

If something doesn't work the way you expect, tell us or reach out to your BambooHR contact.

Disclaimer

The BambooHR MCP server connects you to third-party AI tools, which can produce inaccurate or incomplete responses. BambooHR isn't responsible for errors in AI-generated output or for actions taken in your account based on those responses. Always verify information and review actions before confirming them.