Publikt API: Publik MCP

Simployer MCP Tools – Kundguide

Översikt

Simployer MCP-servern (Model Context Protocol) gör det möjligt för AI-assistenter och applikationer att säkert få åtkomst till dina HR-data via ett standardiserat gränssnitt. Oavsett om du bygger egna AI-lösningar eller integrerar med plattformar som Claude Desktop eller ChatGPT, ger dessa verktyg smidig åtkomst till medarbetarinformation, organisationsstrukturer, frånvarohantering, kompensationsdata och mer.

Vad är Model Context Protocol (MCP)?

Model Context Protocol (MCP) är ett öppet protokoll som gör det möjligt för AI-assistenter att säkert få åtkomst till externa datakällor och verktyg. MCP-servern fungerar som en brygga mellan AI-applikationer (som Claude, ChatGPT eller anpassade LLM-lösningar) och Simployer-API:et och tillhandahåller:

• Standardiserat gränssnitt: Enhetlig API-åtkomst oavsett AI-plattform

• Säker autentisering: JWT-baserad autentisering för alla anrop

• Verktygsupptäckt: Automatisk upptäckt av tillgängliga funktioner

• Strukturerade svar: Väldefinierade scheman för alla operationer

Viktiga fördelar

• AI-redo: Fungerar sömlöst med Claude, ChatGPT och andra MCP-kompatibla AI-plattformar

• Säker: JWT-baserad autentisering säkerställer att dina data förblir skyddade

• Omfattande: Åtkomst till över 17 HR-datamoduler via ett gemensamt gränssnitt

• Standardiserad: Följer det öppna MCP-protokollet för konsekvent integration

Snabbstart

Förutsättningar

• Ett aktivt Simployer-konto

• En JWT-åtkomsttoken (se Autentisering)

• En MCP-kompatibel klient (Claude Desktop, anpassad applikation osv.)

Transportprotokoll

Simployer MCP-servern stöder två transportmetoder:

• Streamable HTTP (Rekommenderad): Modernt tillståndslöst protokoll som använder POST /mcp

  • Slutpunkt: https://mcp-alexis.simployer.com/mcp

  • Använd detta för alla nya integrationer

• Server-Sent Events (SSE) (Äldre): För bakåtkompatibilitet med äldre MCP-klienter

  • Slutpunkter: /sse och /messages

  • Används endast om klienten kräver SSE

Autentisering

Alla anrop till Simployer MCP-servern kräver en giltig JWT (JSON Web Token) från ditt Simployer-konto.

Hämta token

• Logga in på ditt Simployer-konto

• Gå till Inställningar → Åtkomsttoken

• Generera eller hämta din token

• Kopiera token (du behöver den för konfiguration)

Använda token

Inkludera token i Authorization-headern för alla anrop:

Authorization: Bearer YOUR_JWT_TOKEN  

Säkerhetsrekommendationer

• Förvara token säkert och lägg den aldrig i versionshantering

• Rotera token regelbundet

• Använd miljövariabler för att lagra token

• Återkalla token omedelbart om den komprometteras

Tillgängliga moduler

Simployer MCP-servern ger åtkomst till följande HR-datamoduler:

Verktygsreferens

Medarbetarhantering

getAllEmployees

Hämtar en lista över medarbetare med valfri filtrering och paginering.

Parameter:

Available Filters:

Example Request:

{  "jsonrpc": "2.0",  "id": "1",  "method": "tools/call",  "params": {    "name": "getAllEmployees",    "arguments": {      "limit": 100,      "filters": {        "active": true,        "departmentId": "dept-123"      }    }  } } 

Vanliga användningsområden

”Visa alla aktiva medarbetare i Engineering-avdelningen”

”Lista medarbetare på New York-kontoret”

”Hitta medarbetare med titeln ’Senior Developer’”

getEmployeeById

Hämtar en specifik medarbetare baserat på deras unika ID.

Parametrar:

Example Request:

{  "jsonrpc": "2.0",  "id": "2",  "method": "tools/call",  "params": {    "name": "getEmployeeById",    "arguments": {      "employeeId": "12345"    }  } } 

updateEmployee

Uppdaterar specifika fält för en medarbetare i Simployer-systemet.

Parametrar:

Updatable Fields:

Example Request:

{  "jsonrpc": "2.0",  "id": "3",  "method": "tools/call",  "params": {    "name": "updateEmployee",    "arguments": {      "employeeId": "12345",      "data": {        "title": "Senior Developer",        "division": "Engineering"      }    }  } } 

Ytterligare medarbetarverktyg

• getEmployeeCountByDepartment – Räkna medarbetare per avdelning

• getEmployeeCountByOffice – Räkna medarbetare per kontor

• getEmployeeCountByDivision – Räkna medarbetare per division

• calculateTurnover – Beräkna personalomsättning

• getOffboardings – Lista avslutade medarbetare

Avdelningshantering

getAllDepartments

Hämtar alla avdelningar från Simployer-API:et med valfri filtrering.

Parametrar:

Available Filters:

Example Request:

{  "jsonrpc": "2.0",  "id": "4",  "method": "tools/call",  "params": {    "name": "getAllDepartments",    "arguments": {      "limit": 50,      "filters": {        "companyId": "67890"      }    }  } } 

getDepartmentById

Hämtar en specifik avdelning baserat på dess unika ID.

Parametrar:

updateDepartment

Uppdaterar avdelningsinformation.

Frånvarohantering

getAllLeaves

Hämtar all frånvaro från Simployer-API:et med valfri filtrering.

Parametrar:

Available Filters:

Notering om datumfiltrering

Filtren startDate och endDate tillämpas lokalt efter att frånvaro har hämtats från API:et. När båda filtren anges returneras frånvaro där antingen frånvarons startDate eller endDate faller inom det angivna datumintervallet.

Example Request:

{  "jsonrpc": "2.0",  "id": "5",  "method": "tools/call",  "params": {    "name": "getAllLeaves",    "arguments": {      "limit": 200,      "filters": {        "employeeId": "12345",        "startDate": "2024-07-01",        "endDate": "2024-07-31"      }    }  } } 

getLeaveById

Hämtar en specifik frånvaro baserat på dess unika ID.

Parametrar:

updateLeave

Uppdaterar frånvarostatus eller detaljer.

Kompensationshantering

Ordinarie ersättning

Tillgängliga verktyg:

• getAllCompensations – Lista/sök ersättningsposter

• getCompensationById – Hämta ersättningsdetaljer

• updateCompensation – Uppdatera ersättningsinformation

Tillgängliga filter för getAllCompensations:

Bonusersättning

Tillgängliga verktyg:

• getAllBonusCompensations – Lista/sök bonusposter

• getBonusCompensationById – Hämta bonusdetaljer

• updateBonusCompensation – Uppdatera bonusinformation

Tilläggsersättning

Tillgängliga verktyg:

• getAllAdditionalCompensations – Lista/sök tilläggsersättning

• getAdditionalCompensationById – Hämta detaljer för tilläggsersättning

• updateAdditionalCompensation – Uppdatera tilläggsersättning

Kontorshantering

Tillgängliga verktyg:

• getAllOffices – Lista/sök kontor med filtrering

• getOfficeById – Hämta kontorsdetaljer

• updateOffice – Uppdatera kontorsinformation

Projekthantering

Tillgängliga verktøy:

• getAllProjects – Lista/sök projekt

• getProjectById – Hämta projektdetaljer

• updateProject – Uppdatera projektinformation

Tillgängliga filter för getAllProjects:

Företagshantering

Tillgängliga verktyg:

• getCompanyById – Hämta företagsinformation (endast läsbehörighet)

Teamhantering

Tillgängliga verktyg:

• getAllTeams – Lista/sök team

• getTeamById – Hämta teamdetaljer

• updateTeam – Uppdatera teaminformation

Medarbetar–team-referenser

Tillgängliga verktyg:

• getAllEmployeeTeamReferences – Lista kopplingar mellan medarbetare och team

• getEmployeeTeamReferenceById – Hämta specifik koppling

• updateEmployeeTeamReference – Uppdatera teamtillhörighet

Anställningshantering

Tillgängliga verktyg:

• getAllEmployments – Lista/sök anställningar

• getEmploymentById – Hämta anställningsdetaljer

• updateEmployment – Uppdatera anställningsinformation

Hantering av anställningstyper

Tillgängliga verktyg:

• getAllEmploymentTypes – Lista/sök anställningstyper

• getEmploymentTypeById – Hämta detaljer för anställningstyp

• updateEmploymentType – Uppdatera anställningstyp

Kostnadsställeantering

Tillgängliga verktyg:

• getAllCostCenters – Lista/sök kostnadsställen

• getCostCenterById – Hämta kostnadsställe-detaljer

• updateCostCenter – Uppdatera kostnadsställeinformation

Hantering av frånvarotransaktioner

Tillgängliga verktyg:

• getAllLeaveTransactions – Lista/sök frånvarotransaktioner

• getLeaveTransactionById – Hämta transaktionsdetaljer (endast läsbehörighet)

Barnhantering

Tillgängliga verktyg:

• getAllChildren – Lista/sök barnposter

• getChildById – Hämta barndetaljer

• updateChild – Uppdatera barninformation

Tidrapportering

Tidrapporter:

• getAllTimesheets – Lista/sök tidrapporter

• getTimesheetById – Hämta tidrapportdetaljer (endast läsbehörighet)

Tidrapportposter:

• getAllTimesheetEntries – Lista/sök tidrapportposter

• getTimesheetEntryById – Hämta postdetaljer

• updateTimesheetEntry – Uppdatera tidrapportpost

Typer av tidrapportposter:

• getAllTimesheetEntryTypes – Lista/sök posttyper

• getTimesheetEntryTypeById – Hämta posttypdetaljer (endast läsbehörighet)

Arbetsveckohantering

Tillgängliga verktyg:

• getAllWorkWeeks – Lista/sök arbetsveckokonfigurationer

• getWorkWeekById – Hämta arbetsveckodetaljer

• updateWorkWeek – Uppdatera arbetsveckokonfiguration

Scope-hantering

Tillgängliga verktyg:

• getAllScopes – Lista/sök scopes

• getScopeById – Hämta scopedetaljer

• getScopesByParentId – Hämta scopes baserat på parent-ID

• getScopesByParentType – Hämta scopes baserat på parent-typ

• getScopeEmployeeCount – Hämta antal medarbetare för scope(s)

• scopeEmployeeSearchByName – Kontrollera om medarbetare ingår i scope

• updateScope – Uppdatera scope-konfiguration

Tillgängliga parent-typer:

ANNOUNCEMENT, COMPETENCE, FEATURE_ACCESS_POLICY, FORTNOX_SETTINGS, FRANKLY_SETTINGS, LEAVE_POLICY, MODULE_ACCESS, PROFILE_TEMPLATE, PROJECT, REVIEW_CYCLE, SIMP_INTEGRATION_SETTINGS, TIMESHEET_POLICY, WORKFLOW_TASK, WORKFLOW_TASK_TEMPLATE, WORKFLOW_TEMPLATE_ADDITIONAL_PROPERTIES, EXTENDED_MODULE_ACCESS

Användningsfall och exempel

Medarbetaranalys

Scenario: ”Visa personalomsättning för de senaste 12 månaderna”

Naturlig språkfråga: ”Vad är vår personalomsättning för de senaste 12 månaderna?”

Använda verktyg: calculateTurnover

{  "jsonrpc": "2.0",  "id": "6",  "method": "tools/call",  "params": {    "name": "calculateTurnover",    "arguments": {      "startDate": "2023-01-01",      "endDate": "2024-01-01"    }  } }  

Frånvarohantering

Scenario: ”Visa all godkänd frånvaro för juli 2024 på Gdańsk-kontoret”

Naturlig språkfråga:
”Visa all godkänd frånvaro för juli 2024 på Gdańsk-kontoret”

Använda verktyg:

1. getAllOffices (för att hitta kontors-ID)

2. getAllEmployees (för att hitta medarbetare på kontoret)

3. getAllLeaves (för att hämta frånvaro med filter)

Steg-för-steg:

• Hämta kontors-ID för Gdańsk genom att använda getAllOffices med filtret city: "Gdańsk"

• Hämta alla medarbetare på kontoret genom att använda getAllEmployees med filtret officeId: <office-id>

• Hämta all frånvaro för dessa medarbetare i juli 2024 genom att använda getAllLeaves med filtren startDate: "2024-07-01", endDate: "2024-07-31"

Medarbetarsök

Scenario: ”Hitta alla aktiva medarbetare i Engineering-avdelningen”

Naturlig språkfråga:
”Hitta alla aktiva medarbetare i Engineering-avdelningen”

Använda verktyg:
getAllEmployees

Exempelförfrågan:

{  "jsonrpc": "2.0",  "id": "7",  "method": "tools/call",  "params": {    "name": "getAllEmployees",    "arguments": {      "filters": {        "active": true,        "departmentId": "dept-123"      },      "limit": 100    }  } }  

Felhantering

Format för felsvar

All errors follow the JSON-RPC 2.0 format:

{  "jsonrpc": "2.0",  "id": "1",  "error": {    "code": -32603,    "message": "Internal server error",    "data": {      "details": "Additional error information"    }  } } 

Common Error Codes