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 configuration 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 configuration 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. Agentic Data Plane injects the provider’s stored per-user token on each tool call.

The create form turns Enable code mode on by default for this server type. rpk ai mcp-server create has no code-mode flag. To add code mode from the CLI, create a Code MCP server named <server-name>-code with --code.mcp-servers <server-name>. 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.

Expose BambooHR data as SQL tables

The BambooHR server can also present its employee directory as read-only SQL tables, so an agent can filter records the way it would query a database. SQL exposure is the Enabled toggle under Queryable in the server’s configuration. If SQL tools are available in your organization, the create form shows Queryable with Enabled on, so a server you create there is queryable unless you turn it off. Otherwise the form doesn’t show Queryable, and the server starts with SQL exposure off. Creating a server with rpk ai leaves SQL exposure off unless the managed configuration sets it. An existing server keeps the setting it was saved with. To change it, open the server’s edit form, which shows Queryable if SQL tools are available in your organization or if the server was saved with SQL exposure on. SQL exposure adds two tools:

  • list_tables: Return the table catalog. For each table, the catalog lists its columns and their types, which columns can be filtered and with which operators, whether each filter is exact, the page-size limit, and a schema fingerprint that every query response repeats so a caller can tell when the catalog changed.

  • execute_query: Run one query against a table and return a page of rows plus a cursor for the next page.

The one table is employee_directory, the company’s published employee directory, read in a single request that the server then pages itself, at most 1000 rows a page. The table offers no filters, so a query reads the whole directory and filters the rows it reads back.

The directory holds what the company publishes, so it isn’t a complete employee list. BambooHR leaves out employees the company excludes from the directory, along with inactive and former employees, and a field the company doesn’t share comes back empty. A query fails with a 403 when the directory isn’t shared with the caller, and with a 404 when the directory has no employees.

The other BambooHR tools stay plain tools.

To turn SQL exposure on in the managed configuration, add "queryable": {"enabled": true} to the BambooHR configuration in Create the managed MCP server.

With SQL exposure on, the two tools are available to every caller of the server, including agents. Turn off Enabled on a server whose agents should only reach the curated BambooHR tools.

To trim the catalog table by table, hide columns, require filters, retype a column, or serve a table under another name, use the SQL exposure tab on the server’s page. That tab works the same way for every managed type that offers SQL tables. See Narrow what the SQL tools expose. If the server’s page has no SQL exposure tab, narrowing isn’t enabled for your organization. The Enabled setting on the server’s configuration still turns the two SQL tools on and off.

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