AnythingMCP
Back to Guides

HR WORKS MCP Server — HR & Payroll tedesco per Agenti AI

Collega HR WORKS a qualsiasi agente AI tramite MCP. 31 tool pre-costruiti sulla REST API v2: dipendenti, assenze, malattie, orari di lavoro, progetti, candidati. La piattaforma HR di Friburgo, AI-ready.

Pre-built adapter available on AnythingMCP Cloud

Skip the self-hosted setup — install this adapter in one click with a free trial. No credit card required.

Install on Cloud — Free Trial

HR WORKS per Agenti AI

HR WORKS (ex HRworks) è la piattaforma SaaS HR/payroll di Friburgo, usata da ~20.000 PMI nella regione DACH. La REST API v2 espone l'intero dataset operativo — dipendenti, assenze, malattie, orari di lavoro, smart working, progetti, candidati, unità organizzative, festività, centri di costo — e AnythingMCP lo impacchetta tutto in un singolo adapter MCP drop-in con 31 tool pre-costruiti.

Perché un adapter MCP per HR WORKS

HR WORKS non espone una API key persistente. Bisogna fare POST {accessKey, secretAccessKey} su /v2/authentication e ricevere un JWT da 15 minuti che viene poi inviato come Authorization: Bearer <token> su ogni chiamata successiva. La vita breve del token, combinata con i rate limit per-tenant e il pattern dual-identifier (numero di matricola o username sulla maggior parte degli endpoint), fa inciampare quasi tutte le integrazioni fai-da-te.

L'adapter AnythingMCP gestisce:

  • Il contratto bearer-token (tu fornisci il token; l'adapter lo invia su ogni chiamata)
  • Sia produzione che la sandbox api.demo-hrworks.de tramite l'override HRWORKS_BASE_URL
  • I parametri opzionali personIdentifierType / usePersonnelNumbers dove applicabile
  • La regola del massimo intervallo di 1 anno sugli endpoint di listing
  • Un test di integrazione live che dimostra che l'header bearer è effettivamente iniettato (InvalidBearerTokenError invece di MissingAuthorizationHeaderError)

Setup Rapido

Step 1: Deploy AnythingMCP

git clone https://github.com/HelpCode-ai/anythingmcp.git
cd anythingmcp && docker compose up -d

Step 2: Genera un JWT da HR WORKS

Nell'admin HR WORKS: Impostazioni → API → Genera Access Key per ottenere accessKey + secretAccessKey. Poi scambiali per un JWT:

curl -X POST https://api.hrworks.de/v2/authentication \
  -H 'Content-Type: application/json' \
  -d '{"accessKey":"YOUR_ACCESS_KEY","secretAccessKey":"YOUR_SECRET_ACCESS_KEY"}'

La risposta contiene {"token": "eyJ..."}. Lifetime token ~15 minuti — per workflow brevi va bene; per agenti long-running, wrappa l'adapter in un proxy che fa refresh automatico.

Step 3: Importa l'Adapter

Apri http://localhost:3000/connectors/store, clicca Import su HR WORKS e incolla il JWT in HRWORKS_TOKEN.

Per la sandbox: imposta anche HRWORKS_BASE_URL=https://api.demo-hrworks.de e usa credenziali sandbox-issued.

Step 4: Collega l'Agente AI

{
  "mcpServers": {
    "hrworks": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

Tool disponibili (31)

Connettività & Configurazione

| Tool | Cosa restituisce | |------|------------------| | hrworks_health_check | Raggiungibilità API — no auth richiesta | | hrworks_list_organization_units | Tutte le unità organizzative attive | | hrworks_get_organization_unit | Record completo unità organizzativa | | hrworks_list_permanent_establishments | Sedi operative permanenti | | hrworks_list_holidays | Festività per regione/anno | | hrworks_list_cost_centers | Centri di costo configurati nel tenant |

Persone

| Tool | Cosa restituisce | |------|------------------| | hrworks_list_persons | Directory dipendenti con filtri | | hrworks_get_person | Record completo dipendente | | hrworks_list_persons_master_data | Dati anagrafici (attributi HR-rilevanti) | | hrworks_get_persons_today | Snapshot dei dipendenti attivi oggi | | hrworks_list_present_persons | Persone attualmente presenti (ufficio/remoto) | | hrworks_get_leave_account | Saldo conto ferie per persona |

Assenze & Tempo

| Tool | Cosa restituisce | |------|------------------| | hrworks_list_absences | Assenze su un intervallo di date | | hrworks_list_absence_types | Tipi di assenza configurati | | hrworks_list_vacation_types | Catalogo tipi di ferie | | hrworks_list_sick_leaves | Malattie su un intervallo di date | | hrworks_list_sick_leave_types | Categorie di malattia | | hrworks_list_remote_work | Voci di smart working / remote | | hrworks_list_working_times | Voci orario lavoro (max 1 anno o 31 giorni con interval=days) | | hrworks_list_time_recording_regulations | Regole di rilevazione presenze in vigore |

Progetti & Recruiting

| Tool | Cosa restituisce | |------|------------------| | hrworks_list_projects | Progetti con stato | | hrworks_get_project | Record completo progetto | | hrworks_list_project_customers | Clienti collegati ai progetti | | hrworks_list_job_applications | Candidature aperte | | hrworks_list_posts | Annunci di lavoro | | hrworks_get_post | Annuncio completo incl. descrizione | | hrworks_list_applicants | Candidati in pipeline | | hrworks_get_applicant | Record completo candidato |

Casi d'uso per Agenti AI

  • "Chi è in ferie la prossima settimana nel team engineering?" — manager self-service per assenze
  • "Quanti giorni di malattia ha avuto il magazzino in Q1?" — analytics HR
  • "Mostra totali orario lavoro per Jane Doe a marzo 2026" — preparazione straordinari/payroll
  • "Lista candidati attivi per il ruolo Frontend Berlino" — handoff recruiter
  • "Quali dipendenti erano presenti nell'ufficio di Friburgo oggi?" — vista facility/sicurezza

Convenzioni Identifier

La maggior parte degli endpoint persona accetta o il numero di matricola HR WORKS o lo username. Usa i parametri opzionali personIdentifierType / usePersonnelNumbers quando l'identifier che hai a disposizione non è il default — l'adapter li propaga.

Intervalli di date: massimo 1 anno

hrworks_list_absences, hrworks_list_sick_leaves, hrworks_list_remote_work, hrworks_list_working_times richiedono ISO beginDate / endDate (YYYY-MM-DD). L'API HR WORKS limita lo span a 1 anno (o 31 giorni con interval=days). Per range più lunghi, paginare anno per anno e aggregare lato client.

Refresh token — limitazione nota

Questo adapter invia un singolo bearer token statico. Quando il JWT scade (~15 min), l'API ritorna 401 e devi re-importare un token fresco. Per workflow long-running, configura un cron che faccia refresh tramite /v2/authentication e aggiorni la env var HRWORKS_TOKEN del connettore via la admin API di AnythingMCP.

Prossimi passi