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

The moment you start building something that integrates with HiBob, a people ops sync, an onboarding automation, an internal tool that surfaces employee data, you need details that only live in the API's responses.

How does HiBob nest fields under categories like work, about, and personal? Which fields are IDs versus display names? What does a time-off request object actually return?

Without the MCP connection, answering those means leaving the editor, authenticating against HiBob'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 HiBob's data model and query real employee records without leaving Cursor, we'll show you how to connect HiBob with Merge Agent Handler's HiBob MCP server.

How it works

Merge Agent Handler connects Cursor to the HiBob 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 HiBob.

Once authenticated, Merge stores and manages your HiBob credentials, so you never expose API keys in your environment or rotate them by hand.

Related: How to use the HiBob 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 HiBob account with API access enabled (Service User credentials required for API key generation)

If you want to connect Merge Agent Handler's HiBob 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 HiBob 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 HiBob MCP with Codex

4. Authenticate HiBob

Open a Cursor chat in your project and try a prompt such as: "Fetch one employee record and show the full field structure, including how fields are grouped under categories like work and about, so I can map them before I write the sync."

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

{{this-blog-only-cta}}

HiBob MCP FAQ

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

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

With HiBob connected, Cursor can:

• Inspect the employee object before writing a parser: fetch a real record to see how HiBob groups fields under categories like work, about, and personal, so the deserialization code you write matches the actual nesting

• Resolve field IDs versus display names before writing a mapping: pull the field metadata so the sync you write maps HiBob's internal field IDs to your schema correctly instead of guessing from labels

• Check the people-search response before writing the query: fetch a real search result to see how the fields selection and filters behave before you write the request that powers your integration

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

• Confirm named-list values before writing validation or enums: pull the lists behind fields like department, site, and employment type so your type definitions and validation match HiBob's actual values

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

Why use Merge Agent Handler vs. HiBob's official MCP server?

You can connect directly to HiBob, either through HiBob's own MCP server or your own integration on top of its API.

For a single developer on one HiBob account, that's workable: generate Service User credentials, authenticate, and start making calls.

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

A HiBob token carries that account's 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 HiBob-specific server only solves HiBob. The moment a customer or internal team runs Workday or BambooHR instead, you're back to building and authenticating another integration.

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

You define exactly which HiBob operations each agent can call, so an agent that inspects employee structure for code generation can read it without reaching write operations. Every call is 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 HiBob to Cursor?

HiBob's API data, the category-nested employee object, the field-ID structure, the time-off request shape, the named lists behind enum fields, isn't something you can accurately reconstruct from documentation alone.

These are real-response details: fields are grouped under categories rather than returned flat, custom fields carry internal IDs that differ from their labels, and enum fields draw from named lists you have to read to know the valid values.

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

Can I use Merge's HiBob MCP with my employees?

Yes, Merge for Workforce is built to help organizations provision, secure, and govern how employees connect AI tools like Cursor to systems like HiBob.

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 sensitive 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 HiBob MCP to write syncs against the real field structure, build mappings grounded in actual field IDs, and write validation tied to real named-list values, and more, while IT keeps centralized control over which employee data each agent can reach.