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

Tools as of August 13, 2026. Names below are the tool names as they appear in an MCP client. We'll keep adding tools based on customer feedback.

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.

Fields and metadata

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

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.

Reports

Run reports already built in BambooHR.

Time off

One of the highest-traffic areas in BambooHR.

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.

Goal comments

Hiring

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

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.

Files

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

Utilities

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

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

1. The client sends an MCP tool call to https://{your-subdomain}.bamboohr.com/api/mcp with an OAuth access token.
2. The server authenticates the request and identifies the user.
3. It validates the request and checks that the user has permission to perform the action.
4. It calls the appropriate BambooHR API endpoints on the user's behalf.
5. 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.

Related pages

• BambooHR and AI
• Claude Connector
• ChatGPT Connector