Offentlig API: Offentlig MCP

Simployer MCP Tools – Kundeguide

Oversikt

Simployer MCP-serveren (Model Context Protocol) gjør det mulig for AI-assistenter og applikasjoner å få sikker tilgang til dine HR-data gjennom et standardisert grensesnitt. Enten du bygger egne AI-løsninger eller integrerer med plattformer som Claude Desktop eller ChatGPT, gir disse verktøyene sømløs tilgang til ansattinformasjon, organisasjonsstrukturer, fraværshåndtering, kompensasjonsdata og mer.

Hva er Model Context Protocol (MCP)?

Model Context Protocol (MCP) er en åpen protokoll som gjør det mulig for AI-assistenter å få sikker tilgang til eksterne datakilder og verktøy. MCP-serveren fungerer som en bro mellom AI-applikasjoner (som Claude, ChatGPT eller egendefinerte LLM-løsninger) og Simployer-API-et, og tilbyr:

• Standardisert grensesnitt: Konsistent API-tilgang uavhengig av AI-plattform

• Sikker autentisering: JWT-basert autentisering for alle forespørsler

• Verktøyoppdagelse: Automatisk oppdagelse av tilgjengelig funksjonalitet

• Strukturerte responser: Veldefinerte skjemaer for alle operasjoner

Viktige fordeler

• AI-klar: Fungerer sømløst med Claude, ChatGPT og andre MCP-kompatible AI-plattformer

• Sikker: JWT-basert autentisering sikrer at dataene dine forblir beskyttet

• Omfattende: Tilgang til mer enn 17 HR-datamoduler gjennom ett samlet grensesnitt

• Standardisert: Følger den åpne MCP-protokollen for konsistent integrasjon

Kom raskt i gang

Forutsetninger

• En aktiv Simployer-konto

• Et JWT-tilgangstoken (se Autentisering)

• En MCP-kompatibel klient (Claude Desktop, egendefinert applikasjon osv.)

Transportprotokoller

Simployer MCP-serveren støtter to transportmetoder:

• Streamable HTTP (Anbefalt): Moderne statsløs protokoll som bruker POST /mcp

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

  • Bruk denne for alle nye integrasjoner

• Server-Sent Events (SSE) (Eldre): For bakoverkompatibilitet med eldre MCP-klienter

  • Endepunkter: /sse og /messages

  • Brukes kun hvis klienten krever SSE

For egendefinerte integrasjoner skal du alltid bruke Streamable HTTP-endepunktet på
https://mcp-alexis.simployer.com/mcp.

Oppsett av Claude Desktop

• Åpne innstillingene i Claude Desktop

• Gå til konfigurasjon av MCP-servere

• Legg til følgende konfigurasjon:

• Start Claude Desktop på nytt

• Test ved å spørre: «List opp alle ansatte i Engineering-avdelingen»

Oppsett av egendefinert klient

Bruk MCP-endepunktet sammen med JWT-tokenet ditt:

Autentisering

Alle forespørsler til Simployer MCP-serveren krever en gyldig JWT (JSON Web Token) fra Simployer-kontoen din.

Hente token

• Logg inn på Simployer-kontoen din

• Gå til Innstillinger → Tilgangstokener

• Generer eller hent tokenet ditt

• Kopier tokenet (du trenger det for konfigurasjon)

Bruke tokenet

Inkluder tokenet i Authorization-headeren for alle forespørsler:

Authorization: Bearer YOUR_JWT_TOKEN  

Sikkerhetsanbefalinger

• Hold tokenet sikkert og legg det aldri inn i versjonskontroll

• Roter token regelmessig

• Bruk miljøvariabler for å lagre token

• Tilbakekall token umiddelbart dersom det kompromitteres

Tilgjengelige moduler

Simployer MCP-serveren gir tilgang til følgende HR-datamoduler:

Verktøyreferanse

Ansattadministrasjon

getAllEmployees

Henter en liste over ansatte med valgfri filtrering og paginering.

Available Filters:

Eksempel:

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

Vanlige bruksområder

«Vis alle aktive ansatte i Engineering-avdelingen»

«List opp ansatte ved New York-kontoret»

«Finn ansatte med tittelen ‘Senior Developer’»

getEmployeeById

Henter en spesifikk ansatt basert på deres unike ID.

Parametere:

Example Request:

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

updateEmployee

Oppdaterer spesifikke felt for en ansatt i Simployer-systemet.

Parametere:

Updatable Fields:

Example Request:

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

Ytterligere ansattverktøy

• getEmployeeCountByDepartment – Tell ansatte per avdeling

• getEmployeeCountByOffice – Tell ansatte per kontor

• getEmployeeCountByDivision – Tell ansatte per divisjon

• calculateTurnover – Beregn turnover-rate

• getOffboardings – List ansatte som er avsluttet

Avdelingsadministrasjon

getAllDepartments

Henter alle avdelinger fra Simployer-API-et med valgfri filtrering.

Parametere:

Available Filters:

Example Request:

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

getDepartmentById

Henter en spesifikk avdeling basert på dens unike ID.

Parametere:

updateDepartment

Oppdaterer avdelingsinformasjon.

Fraværshåndtering

getAllLeaves

Henter alle fravær fra Simployer-API-et med valgfri filtrering.

Parametre:

Available Filters:

Merknad om datofiltrering

Filtrene startDate og endDate brukes lokalt etter at fravær er hentet fra API-et. Når begge filtrene er angitt, returneres fravær der enten fraværets startDate eller endDate faller innenfor det spesifiserte datointervallet.

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

Henter et spesifikt fravær basert på dets unike ID.

Parametere:

updateLeave

Oppdaterer fraværsstatus eller -detaljer.

Kompensasjonshåndtering

Ordinær kompensasjon

Tilgjengelige verktøy:

• getAllCompensations – List/søk kompensasjonsoppføringer

• getCompensationById – Hent kompensasjonsdetaljer

• updateCompensation – Oppdater kompensasjonsinformasjon

Tilgjengelige filtre for getAllCompensations:

Bonuskompensasjon

Tilgjengelige verktøy:

• getAllBonusCompensations – List/søk bonusoppføringer

• getBonusCompensationById – Hent bonusdetaljer

• updateBonusCompensation – Oppdater bonusinformasjon

Tilleggskompensasjon

Tilgjengelige verktøy:

• getAllAdditionalCompensations – List/søk tilleggskompensasjon

• getAdditionalCompensationById – Hent detaljer for tilleggskompensasjon

• updateAdditionalCompensation – Oppdater tilleggskompensasjon

Kontoradministrasjon

Tilgjengelige verktøy:

• getAllOffices – List/søk kontorer med filtrering

• getOfficeById – Hent kontordetaljer

• updateOffice – Oppdater kontorinformasjons

Prosjektadministrasjon

Tilgjengelige verktøy:

• getAllProjects – List/søk prosjekter

• getProjectById – Hent prosjektdetaljer

• updateProject – Oppdater prosjektinformasjon

Tilgjengelige filtre for getAllProjects:

Selskapsadministrasjon

Tilgjengelige verktøy:

• getCompanyById – Hent selskapsinformasjon (kun lesetilgang)

Teamadministrasjon

Tilgjengelige verktøy:

• getAllTeams – List/søk team

• getTeamById – Hent teamdetaljer

• updateTeam – Oppdater teaminformasjon

Ansatt–team-referanser

Tilgjengelige verktøy:

• getAllEmployeeTeamReferences – List tilknytninger mellom ansatte og team

• getEmployeeTeamReferenceById – Hent spesifikk tilknytning

• updateEmployeeTeamReference – Oppdater teamtilhørighet

Ansettelsesadministrasjon

Tilgjengelige verktøy:

• getAllEmployments – List/søk ansettelsesforhold

• getEmploymentById – Hent ansettelsesdetaljer

• updateEmployment – Oppdater ansettelsesinformasjon

Administrasjon av ansettelsestyper

Tilgjengelige verktøy:

• getAllEmploymentTypes – List/søk ansettelsestyper

• getEmploymentTypeById – Hent detaljer for ansettelsestype

• updateEmploymentType – Oppdater ansettelsestype

Kostnadsstedadministrasjon

Tilgjengelige verktøy:

• getAllCostCenters – List/søk kostnadssteder

• getCostCenterById – Hent detaljer for kostnadssted

• updateCostCenter – Oppdater kostnadsstedinformasjon

Fraværstransaksjonsadministrasjon

Tilgjengelige verktøy:

• getAllLeaveTransactions – List/søk fraværstransaksjoner

• getLeaveTransactionById – Hent transaksjonsdetaljer (kun lesetilgang)

Barneadministrasjon

Tilgjengelige verktøy:

• getAllChildren – List/søk barneoppføringer

• getChildById – Hent detaljer om barn

• updateChild – Oppdater barneinformasjon

Timelisteadministrasjon

Timelister:

• getAllTimesheets – List/søk timelister

• getTimesheetById – Hent timelistedetaljer (kun lesetilgang)

Timelisteoppføringer:

• getAllTimesheetEntries – List/søk timelisteoppføringer

• getTimesheetEntryById – Hent oppføringsdetaljer

• updateTimesheetEntry – Oppdater timelisteoppføring

Typer timelisteoppføringer:

• getAllTimesheetEntryTypes – List/søk oppføringstyper

• getTimesheetEntryTypeById – Hent oppføringstype-detaljer (kun lesetilgang)

Arbeidsukeadministrasjon

Tilgjengelige verktøy:

• getAllWorkWeeks – List/søk arbeidsukekonfigurasjoner

• getWorkWeekById – Hent detaljer for arbeidsuke

• updateWorkWeek – Oppdater arbeidsukekonfigurasjon

Scope-administrasjon

Tilgjengelige verktøy:

• getAllScopes – List/søk scopes

• getScopeById – Hent scopedetaljer

• getScopesByParentId – Hent scopes basert på parent-ID

• getScopesByParentType – Hent scopes basert på parent-type

• getScopeEmployeeCount – Hent antall ansatte for scope(r)

• scopeEmployeeSearchByName – Sjekk om ansatt er innenfor scope

• updateScope – Oppdater scope-konfigurasjon

Tilgjengelige 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

Bruksområder og eksempler

Ansattanalyse

Scenario: «Vis turnover-rate for de siste 12 månedene»

Naturlig språk-spørring: «Hva er vår turnover-rate for de siste 12 månedene?»

Verktøy brukt: calculateTurnover

Eksempelforespørsel:

Fraværshåndtering

Scenario: «Vis alle godkjente fravær for juli 2024 ved Gdańsk-kontoret»

Naturlig språk-spørring: «Vis alle godkjente fravær for juli 2024 ved Gdańsk-kontoret»

Verktøy brukt:

1. getAllOffices (for å finne kontor-ID)

2. getAllEmployees (for å finne ansatte på kontoret)

3. getAllLeaves (for å hente fravær med filtre)

Steg-for-steg:

• Finn kontor-ID for Gdańsk ved å bruke getAllOffices med filter city: "Gdańsk"

• Hent alle ansatte på kontoret ved å bruke getAllEmployees med filter officeId: <office-id>

• Hent alle fravær for disse ansatte i juli 2024 ved å bruke getAllLeaves med filtrene startDate: "2024-07-01", endDate: "2024-07-31"

Ansattsøk

Scenario: «Finn alle aktive ansatte i Engineering-avdelingen»

Naturlig språk-spørring: «Finn alle aktive ansatte i Engineering-avdelingen»

Verktøy brukt: getAllEmployees

Eksempelforespørsel:

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

Feilhåndtering

Format for feilrespons

Error Response Format

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

Feilsøking

Autentiseringsfeil

• Bekreft at JWT-tokenet ditt er gyldig og ikke utløpt

• Kontroller tokenformat: Bearer YOUR_TOKEN

• Sørg for at tokenet har nødvendige rettigheter

Tilkoblingsproblemer

• Bekreft at serveren er tilgjengelig: curl https://mcp-alexis.simployer.com/health

• Kontroller nettverkstilkobling

• Gå gjennom feilmeldinger i responsen

Tidsavbruddsfeil

• Standard tidsavbrudd: 120 sekunder

• For store spørringer, bruk paginering (limit-parameter)

• Vurder å dele komplekse operasjoner i mindre forespørsler

Beste praksis

Ytelsesoptimalisering

Bruk paginering

• Standard grense: 500 poster per forespørsel

• Bruk alltid paginering når totalCount > limit

• Bruk filtre for å redusere resultatsett når mulig

Filtrer før henting

• Bruk filtre på API-nivå fremfor klientsidefiltrering

• Bruk spesifikke filtre (ID-er, datoer) når mulig

• Kombiner flere filtre for å snevre inn resultatene

Optimalisering av forespørsler

• Samle relaterte forespørsler når mulig

• Bufre ofte brukte data

• Bruk getById-metoder når du kjenner ID-en

Sikkerhet

• Legg aldri tokens i versjonskontroll

• Bruk miljøvariabler for sensitiv informasjon

• Roter tokens regelmessig

• Implementer korrekt feilhåndtering for å unngå eksponering av sensitiv informasjon

• Bruk HTTPS for alle forespørsler

Ratebegrensning

• Vær oppmerksom på API-ets ratebegrensninger

• Implementer eksponentiell backoff ved nye forsøk

• Vurder klientside køhåndtering for applikasjoner med høyt volum

FAQ

Generelt

Spørsmål: Hva er MCP?
Svar: Model Context Protocol (MCP) er en åpen protokoll som gjør det mulig for AI-assistenter å få sikker tilgang til eksterne datakilder og verktøy.

Spørsmål: Må jeg være utvikler for å bruke disse verktøyene?
Svar: Selv om teknisk kompetanse er nyttig, tilbyr mange AI-plattformer (som Claude Desktop) et brukervennlig grensesnitt for bruk av MCP-verktøy.

Spørsmål: Er dataene mine sikre?
Svar: Ja. Alle forespørsler bruker JWT-autentisering og HTTPS-kryptering. Tokenene dine lagres aldri på våre servere.

Integrasjon

Spørsmål: Kan jeg bruke disse verktøyene med ChatGPT?
Svar: Ja, dersom din ChatGPT-implementasjon støtter MCP. Sjekk med din AI-plattformleverandør for MCP-kompatibilitet.

Spørsmål: Hvordan tester jeg om oppsettet fungerer?
Svar: Prøv en enkel spørring som «List alle ansatte» eller «Vis alle avdelinger» via MCP-klienten din.

Spørsmål: Hva gjør jeg hvis jeg får autentiseringsfeil?
Svar: Bekreft at JWT-tokenet er gyldig, ikke utløpt og korrekt formatert i Authorization-headeren.

Support og ressurser

Helsesjekk

• Sjekk serverstatus: GET https://mcp-alexis.simployer.com/health

• Respons: {"status": "ok"}

Ytterligere ressurser

• Simployer Public API-dokumentasjon

• MCP Protocol Specification

• Relatert dokumentasjon: Public API MCP-dokumentasjon