Come collegare HiBob a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → HiBob, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

HiBob + Gemini

La piattaforma HR HiBob (Bob) tramite l'API pubblica con un service user: ricerca e schede dei dipendenti, storico di lavoro, impiego, lifecycle e retribuzione, tabelle personalizzate, liste aziendali, assenze con chi è fuori, richieste, saldi e policy, festività, report salvati, onboarding, attività e documenti. Le scritture sui dati anagrafici sono disattivate all'installazione.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

HIBOB_SERVICE_USER_ID, HIBOB_SERVICE_USER_TOKEN

Step 1 — Ottieni le credenziali

La configurazione richiede circa 10 minuti e serve un amministratore di Bob. Il connettore usa l'API REST pubblica di Bob (https://api.hibob.com/v1) con un service user.

1. In Bob, come amministratore, vai in Settings > Integrations > Automation > Service Users, fai clic su Manage e crea un service user con nome e nome visualizzato. Copia subito il suo ID e il token: il token compare solo quando viene generato. Un token perso si può rigenerare, e quello vecchio smette di valere.
2. Crea un gruppo di permessi (permission group) dedicato e aggiungici il service user. Un gruppo nuovo non ha permessi, quindi concedi solo ciò che usi:
   • People's data > People's fields: View sulle categorie che leggi (almeno root, about, employment e work per hibob_search_people), View history sulle tabelle storiche (work, employment, lifecycle, payroll), Edit dove aggiorni.
   • Access data for: Everyone oppure una condizione. Per impostazione predefinita sono coperte solo le persone in forza; togli la condizione Lifecycle status equals Employed per leggere chi è uscito con show_inactive.
   • People's data > Time off: vedere richieste e saldi, e inviare o annullare richieste se usi quegli strumenti; vedere le richieste private per include_private.
   • Features > Reports: View reports according to people's data access rights.
   • People's data > Tasks and flow > People's tasks: View and mark selected people's tasks as complete.
   • People's data > Docs > [cartella]: View per cartella di documenti, e Upload per la cartella condivisa.
3. Incolla l'ID in HIBOB_SERVICE_USER_ID e il token in HIBOB_SERVICE_USER_TOKEN. Vengono inviati come autenticazione HTTP Basic.
4. Installa il connettore ed esegui hibob_list_employee_fields per verificare l'accesso.

Prima gli id dei campi: hibob_list_employee_fields elenca ogni campo standard e personalizzato con il suo id in notazione a punti (root.displayName, work.department, work.custom.field_123) e l'id di lista dei campi a lista. hibob_list_named_lists e hibob_get_named_list trasformano gli id di lista in nomi (reparti, sedi, qualifiche, calendari).

Cosa legge:

• Persone: hibob_search_people legge molti dipendenti in una sola chiamata (tutti, oppure filtrati solo per root.id o root.email; altri filtri vengono rifiutati), hibob_get_employee una persona per id o email di lavoro, hibob_list_profiles una rubrica rapida. In un'azienda grande l'AI cerca prima con fields: ["root.id"] e poi legge da 50 a 200 id per chiamata.
• Tabelle storiche di una persona (work, employment, lifecycle, salary) e in blocco per molte (work, lifecycle, salary).
• Tabelle personalizzate con le loro colonne e le voci di un dipendente.
• Assenze: chi è fuori in un intervallo di date o in un giorno, richieste cambiate da un certo momento, una richiesta con i suoi giorni, il saldo di un dipendente per un tipo di policy, tipi di policy, codici motivo, policy, e festività e chiusure aziendali con hibob_search_calendar_events.
• Report salvati, eseguiti come righe JSON, CSV o XLSX; quelli grandi vengono generati in background con hibob_request_report_download e scaricati con hibob_download_report_by_name.
• Wizard di onboarding, attività aperte in tutta l'azienda, le attività di un dipendente, le cartelle di documenti e i documenti di un dipendente con link di download.

Cosa scrive dopo l'installazione: hibob_submit_time_off_request (l'AI controlla prima l'unità del tipo di policy con hibob_get_policy_type; la richiesta segue il flusso di approvazione della policy, salvo che un amministratore imposti skip_manager_approval), hibob_cancel_time_off_request e hibob_complete_task.

Disattivati all'installazione: le scritture sui dati anagrafici hibob_update_employee (solo campi, non righe di tabelle), hibob_create_work_entry (promozione, trasferimento, nuovo responsabile), hibob_create_custom_table_entry, hibob_add_named_list_item e hibob_upload_shared_document (un URL pubblico o prefirmato, al massimo 5 MB, visibile al dipendente). Un amministratore del workspace li attiva consapevolmente nel connettore.

Formati dei dati: gli id dei dipendenti sono numeri lunghi inviati come stringhe (3332883884017713238). Le richieste usano la notazione a punti (work.department); le risposte usano chiavi con barre (/work/department) e possono annidare lo stesso valore anche per categoria. I campi a lista contengono id di voci; human_readable: APPEND o REPLACE aggiunge i nomi o li mette al loro posto. Le date sono YYYY-MM-DD; hibob_list_time_off_changes accetta date-ora ISO 8601. I saldi sono nell'unità del tipo di policy (giorni o ore) e le retribuzioni hanno la propria valuta. Dopo un aggiornamento Bob può restituire il valore vecchio per un massimo di 20 secondi.

Omissione silenziosa: un campo senza permesso o con un id sbagliato manca semplicemente dalla risposta, senza errore. Se manca qualcosa, controlla il gruppo di permessi del service user prima di concludere che il valore è vuoto.

Paginazione: ricerca persone, profili, lo storico di un dipendente, le attività aperte (al massimo 5.000) e chi è fuori restituiscono tutto in una volta. Gli strumenti storici in blocco e hibob_search_calendar_events paginano con cursor uguale a response_metadata.next_cursor; l'AI si ferma quando è null.

Limiti: i rate limit valgono per endpoint (la ricerca persone consente 50 richieste al minuto) e rispondono 429. Chi è fuori e gli intervalli del calendario hanno un'ampiezza massima, e le modifiche alle assenze risalgono al massimo a 6 mesi fa.

Errori comuni: 401 indica un ID o un token errato, 403 un permesso mancante nel gruppo del service user, 400 un filtro, un campo o un intervallo di date non valido. Risposte 401 o 403 ripetute possono essere bloccate per un po' dal firewall di Bob, quindi correggi i permessi prima di riprovare.

Il connettore non elabora le buste paga, non modifica le righe delle tabelle storiche con hibob_update_employee e non ha strumenti per approvare o rifiutare richieste di assenza in sospeso.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di HiBob.

Tool disponibili

Esempi di prompt

• "Chi è fuori ufficio la prossima settimana, e con quale policy di assenza?"
• "Mostra lo storico di lavoro di [email protected]: qualifiche, reparti e responsabili con le date di decorrenza."
• "Quanti giorni di ferie restano quest'anno al dipendente 3332883884017713238, e quanti sono in attesa?"
• "Esegui il report salvato "Headcount by department" e riassumilo per sede."
• "Elenca tutte le attività di onboarding aperte e scadute, con il responsabile e il nuovo assunto a cui si riferiscono."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Meta Muse
• Collegare a Microsoft Copilot