Agentic Data Plane

BambooHR Managed MCP Server

The BambooHR managed MCP server lets agents read BambooHR employee directory, time-off, and performance data with the calling user’s OAuth identity. The BambooHR configuration stores the company subdomain and the name of the BambooHR OAuth Provider to authenticate against. OAuth credentials and user tokens come from that provider and the token vault.

After reading this page, you will be able to:

  • Configure the BambooHR managed MCP server with a BambooHR subdomain and user-delegated OAuth

  • Identify the BambooHR tools available to agents

  • Test BambooHR tool calls with an authorized user’s connection

What this MCP server does

Use BambooHR when an agent needs HR context from BambooHR without sharing one upstream API key across every caller. Each caller authorizes with BambooHR, and tool calls run with the BambooHR permissions available to that caller.

Tool What it does

get_employee

Fetches a single employee by ID. Use employee ID 0 to return the authenticated user’s own record. Pass a comma-separated fields list naming the fields you want. Without it, BambooHR returns only the employee ID.

get_employee_directory

Lists all employee directory entries visible to the authenticated user.

get_time_off_requests

Queries time-off requests by date range. You can filter by employee ID, status, or time-off type. Supported statuses are approved, denied, superceded, requested, and canceled.

whos_out

Returns absences and holidays in a date range. If you omit dates, BambooHR returns today through 14 days out.

get_performance_feedback

Returns peer or manager feedback for an employee. You can filter by completed, pending, or all feedback.

Prerequisites

  • Access to the BambooHR Developer Portal, where you register an OAuth 2.0 application.

  • Permission to create an OAuth Provider in Redpanda Agentic Data Plane. See Configure an OAuth Provider.

  • A BambooHR company subdomain, such as mycompany for mycompany.bamboohr.com. The managed config accepts letters, numbers, and hyphens.

  • BambooHR users with the permissions required to read the employee, time-off, or performance data your agent needs.

Configure BambooHR OAuth

  1. In the BambooHR Developer Portal, register an OAuth 2.0 application. Set its redirect URI to the OAuth callback URL for your AI Gateway deployment. BambooHR requires an exact match, including trailing slashes and capitalization.

  2. In Agentic Data Plane, create a custom OAuth Provider for BambooHR with these settings, replacing <subdomain> with your company subdomain:

    Authorization endpoint: https://<subdomain>.bamboohr.com/authorize.php?request=authorize
Token endpoint:         https://<subdomain>.bamboohr.com/token.php?request=token
Scopes:                 employee employee_directory time_off offline_access

    BambooHR expects the client ID and secret in the token request body, so set the token endpoint authentication method to Client Secret (POST). BambooHR returns a refresh token only when the authorization request includes offline_access, so keep that scope.

  3. Store the BambooHR client secret in the Agentic Data Plane secret store, then reference that secret from the OAuth Provider.

BambooHR’s API reference doesn’t list the endpoint behind get_performance_feedback, so the scope it needs isn’t documented. If that tool returns a permission error while the other tools succeed, ask BambooHR which scope your application needs and add it to the provider’s scopes.

Create the managed MCP server

Create a managed MCP server with the BambooHR type. Set the subdomain field and reference the BambooHR OAuth Provider under the userOauth authentication variant. BambooHR supports per-user OAuth only, so the userOauth block is required.

The BambooHR managed config holds the company subdomain and the OAuth provider to authenticate against:

{
  "@type": "type.googleapis.com/redpanda.mcps.bamboohr.v1.BambooHRMCPConfig",
  "subdomain": "mycompany",
  "userOauth": {
    "providerName": "bamboohr"
  }
}

userOauth.providerName is the resource name of the BambooHR OAuth Provider you registered. The provider’s stored per-user token is injected on each tool call.

The create form turns Enable code mode on by default for this server type. rpk ai mcp-server create leaves it off unless you pass --code-mode. See Code Mode.

Authorize and test

Before a caller can use BambooHR tools, the caller must authorize the BambooHR OAuth Provider. After authorization, Redpanda stores the user’s access token in the token vault and subsequent tool calls use that token automatically.

Test the server in the Inspector before you connect it to an agent. Start with get_employee_directory or get_employee with employee ID 0, because both calls confirm that the user’s OAuth connection resolves and BambooHR returns data visible to that user.

Troubleshooting

Symptom What to check

Tool calls return permission errors

Confirm the BambooHR user can access the requested HR data. Restricted BambooHR roles can return permission errors, especially for performance data.

OAuth succeeds, but tool calls fail

Confirm the OAuth Provider endpoints use the same BambooHR subdomain as the MCP server configuration, and that the provider’s scopes include employee, employee_directory, and time_off.

Access works at first, then every call fails until the user reconnects

Confirm the provider’s scopes include offline_access. Without it, BambooHR issues no refresh token.

The server cannot find the BambooHR company

Confirm subdomain contains only the part before .bamboohr.com, such as mycompany.

Next steps