Connect your AI Agents to HiBob in minutes
Available tools
list_employee_documents
List HiBob documents for employee. Returns document metadata including name, upload date, folder, and tags. Does not return document contents - use download URL if provided.
upload_document_from_url
Upload document to HiBob employee folder from URL. Specify folder_type ('shared' or 'confidential'). Optionally add tags. Returns uploaded document ID.
delete_document
Delete HiBob document from employee folder. Requires document_id from list_employee_documents and folder_type ('shared' or 'confidential'). Document deletion is permanent and cannot be undone.
get_folder_metadata
Get HiBob document folder metadata. Returns available folder types and IDs. Use to understand document organization before uploading.
search_employees
Search HiBob employees. Filter by ID or email only (API limitation - use root.id or root.email with equals operator). Returns paginated employee records with work info. Use list_employee_fields first to see available field IDs for the fields parameter.
get_employee
Get detailed HiBob employee by ID. Returns work info, about section, and custom fields. Specify field IDs to limit response size. Use list_employee_fields to see all available fields.
create_employee
Create new HiBob employee. Required: email, firstName, surname, site (must be valid list item), startDate. Returns created employee. Use get_named_list with 'site' to find valid site values first.
update_employee
Update HiBob employee fields. Pass field paths and values (e.g., 'work.title': 'Senior Engineer'). Use list_employee_fields to find valid field paths. Returns updated employee record.
terminate_employee
Terminate HiBob employee with termination date and optional reason. Sets employee status to terminated and records last day of employment. Cannot be undone via API.
uninvite_employee
Revoke HiBob employee's system access. Employee record remains but they cannot log in. Use for immediate access removal without full termination.
list_employee_fields
Get metadata for all HiBob employee fields. Returns paginated field IDs, names, types, and categories. Use field IDs in search_employees and get_employee. No special permissions required.
get_named_list
Get items from HiBob named list (departments, sites, divisions, etc.). Returns paginated list items with IDs and names. Use list_name parameter with values like 'department', 'site', 'division', 'employmentType'.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's HiBob MCP server
FAQs on using Merge's HiBob MCP server
Explore other MCP servers built and managed by Merge
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
