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

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

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 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

Persone

Assenze & Tempo

Progetti & Recruiting

(mostra 30 di 31 tool — installa il connettore per vederli tutti)

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

• Collega HR WORKS a Claude
• Collega HR WORKS a ChatGPT
• Guida MCP per Personio — alternativa DACH HR
• Guida MCP per Kenjo HR — alternativa DACH HR