Public API: Public MCP

Simployer MCP Tools - Customer Guide

Overview

The Simployer MCP (Model Context Protocol) Server enables AI assistants and applications to securely access your HR data through a standardized interface. Whether you're building custom AI solutions or integrating with platforms like Claude Desktop or ChatGPT, these tools provide seamless access to employee information, organizational structures, leave management, compensation data, and more.

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely access external data sources and tools. The MCP server acts as a bridge between AI applications (like Claude, ChatGPT, or custom LLM solutions) and the Simployer API, providing:

• Standardized Interface: Consistent API access regardless of the AI platform
• Secure Authentication: JWT-based authentication for all requests
• Tool Discovery: Automatic discovery of available capabilities
• Structured Responses: Well-defined schemas for all operations

Key Benefits

• AI-Ready: Works seamlessly with Claude, ChatGPT, and other MCP-compatible AI platforms
• Secure: JWT-based authentication ensures your data remains protected
• Comprehensive: Access to 17+ HR data modules through a unified interface
• Standardized: Follows the open MCP protocol for consistent integration

Quick Start

Prerequisites

• An active Simployer account
• A JWT access token (see Authentication)
• An MCP-compatible client (Claude Desktop, custom application, etc.)
  
  

Transport Protocols

The Simployer MCP server supports two transport methods:

• Streamable HTTP (Recommended): Modern stateless protocol using POST /mcp
- Endpoint: https://mcp-alexis.simployer.com/mcp
 - Use this for all new integrations

• Server-Sent Events (SSE) (Legacy): For backward compatibility with older MCP clients
- Endpoints: /sse and /messages
- Only use if your client requires SSE

{
  "mcpServers": {
    "alexishr": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {
        "MCP_SERVER_URL": "https://mcp-alexis.simployer.com/mcp",
        "MCP_AUTH_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

For custom integrations, always use the Streamable HTTP endpoint at https://mcp-alexis.simployer.com/mcp.

Setting Up Claude Desktop

1. Open Claude Desktop settings
2. Navigate to MCP Servers configuration
3. Add the following configuration:

4. Restart Claude Desktop
5. Test by asking: "List all employees in the Engineering department"

Setting Up a Custom Client

Use the MCP endpoint with your JWT token:

curl -X POST https://mcp-alexis.simployer.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

Authentication

All requests to the Simployer MCP server require a valid JWT (JSON Web Token) from your Simployer account.

Obtaining Your Token

1. Log in to your Simployer account
2. Navigate to Settings → Access Tokens
3. Generate or retrieve your token
4. Copy the token (you'll need it for configuration)

Using Your Token

Include the token in the Authorization header for all requests:

Authorization: Bearer YOUR_JWT_TOKEN 

Security Best Practices

• Keep your token secure and never commit it to version control
• Rotate tokens regularly
• Use environment variables to store tokens
• Revoke tokens immediately if compromised

Available Modules

The Simployer MCP server provides access to the following HR data modules:

Tool Reference

Employee Management

getAllEmployees

Retrieves a list of employees with optional filtering and pagination.

Parameters:

Available Filters:

Example Request:

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

Common Use Cases:

• "Show me all active employees in the Engineering department"
• "List employees in the New York office"
• "Find employees with the title 'Senior Developer'"

getEmployeeById

Fetches a specific employee by their unique ID.

Parameters:

Example Request:

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

updateEmployee

Updates specific fields of an employee in the Simployer system.

Parameters:

Updatable Fields:

Example Request:

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

Additional Employee Tools

• getEmployeeCountByDepartment - Count employees by department
• getEmployeeCountByOffice - Count employees by office
• getEmployeeCountByDivision - Count employees by division
• calculateTurnover - Calculate turnover rates
• getOffboardings - List offboarded employees

Department Management

getAllDepartments

Fetches all departments from Simployer API with optional filtering.

Parameters:

Available Filters:

Example Request:

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

getDepartmentById

Fetches a specific department by its unique ID.

Parameters:

updateDepartment

Updates department information.

Leave Management

getAllLeaves

Fetches all leaves from Simployer API with optional filtering.

Parameters:

Available Filters:

Note on Date Filtering:

The startDate and endDate filters are applied locally after fetching leaves from the API. When both filters are provided, leaves are returned where either the leave's startDate or endDate falls within the specified range.

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

Fetches a specific leave by its unique ID.

Parameters:

updateLeave

Updates leave status or details.

Compensation Management

Regular Compensation

Tools Available:

• getAllCompensations - List/search compensation records
• getCompensationById - Get compensation details
• updateCompensation - Update compensation information

Available Filters for getAllCompensations:

Bonus Compensation

Tools Available:

• getAllBonusCompensations - List/search bonus records
• getBonusCompensationById - Get bonus details
• updateBonusCompensation - Update bonus information

Additional Compensation

Tools Available:

• getAllAdditionalCompensations - List/search additional compensation
• getAdditionalCompensationById - Get additional compensation details
• updateAdditionalCompensation - Update additional compensation

Office Management

Tools Available:

• getAllOffices - List/search offices with filtering
• getOfficeById - Get office details
• updateOffice - Update office information

Project Management

Tools Available:

• getAllProjects - List/search projects
• getProjectById - Get project details
• updateProject - Update project information

Available Filters for getAllProjects:

Company Management

Tools Available:

• getCompanyById - Get company information (read-only)

Team Management

Tools Available:

• getAllTeams - List/search teams
• getTeamById - Get team details
• updateTeam - Update team information

Employee Team References

Tools Available:

• getAllEmployeeTeamReferences - List employee-team associations
• getEmployeeTeamReferenceById - Get specific association
• updateEmployeeTeamReference - Update team membership

Employment Management

Tools Available:

• getAllEmployments - List/search employment records
• getEmploymentById - Get employment details
• updateEmployment - Update employment information

Employment Type Management

Tools Available:

• getAllEmploymentTypes - List/search employment types
• getEmploymentTypeById - Get employment type details
• updateEmploymentType - Update employment type

Cost Center Management

Tools Available:

• getAllCostCenters - List/search cost centers
• getCostCenterById - Get cost center details
• updateCostCenter - Update cost center information

Leave Transaction Management

Tools Available:

• getAllLeaveTransactions - List/search leave transactions
• getLeaveTransactionById - Get transaction details (read-only)

Child Management

Tools Available:

• getAllChildren - List/search children records
• getChildById - Get child details
• updateChild - Update child information

Timesheet Management

Timesheets:

• getAllTimesheets - List/search timesheets
• getTimesheetById - Get timesheet details (read-only)

Timesheet Entries:

• getAllTimesheetEntries - List/search timesheet entries
• getTimesheetEntryById - Get entry details
• updateTimesheetEntry - Update timesheet entry

Timesheet Entry Types:

• getAllTimesheetEntryTypes - List/search entry types
• getTimesheetEntryTypeById - Get entry type details (read-only)

Work Week Management

Tools Available:

• getAllWorkWeeks - List/search work week configurations
• getWorkWeekById - Get work week details
• updateWorkWeek - Update work week configuration

Scope Management

Tools Available:

• getAllScopes - List/search scopes
• getScopeById - Get scope details
• getScopesByParentId - Get scopes by parent ID
• getScopesByParentType - Get scopes by parent type
• getScopeEmployeeCount - Get employee count for scope(s)
• scopeEmployeeSearchByName - Check if employee is in scope
• updateScope - Update scope configuration

Parent Types Available:

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

Use Cases & Examples

Employee Analytics

Scenario: "Show me the turnover rate for the last 12 months"

Natural Language Query: "What's our employee turnover rate for the last 12 months?"

Tools Used: calculateTurnover

Example Request:

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

Leave Management

Scenario: "Show all approved leaves for July 2024 in the Gdańsk office"

Natural Language Query: "Show me all approved leaves for July 2024 in the Gdańsk office"

Tools Used: 1. getAllOffices (to find office ID) 2. getAllEmployees (to find employees in that office) 3. getAllLeaves (to get leaves with filters)

Step-by-Step:

1. First, get the office ID for Gdańsk using getAllOffices with filter city: "Gdańsk"
2. Get all employees in that office using getAllEmployees with filter officeId: <office-id>
3. Get all leaves for those employees in July 2024 using getAllLeaves with filters startDate: "2024-07-01", endDate: "2024-07-31"

Employee Search

Scenario: "Find all active employees in the Engineering department"

Natural Language Query: "Find all active employees in the Engineering department"

Tools Used: getAllEmployees

Example Request:

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

Error Handling

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

Troubleshooting

Authentication Errors

• Verify your JWT token is valid and not expired
• Check token format: Bearer YOUR_TOKEN
• Ensure token has necessary permissions

Connection Issues

• Verify server is accessible: curl https://mcp-alexis.simployer.com/health
• Check network connectivity
• Review error messages in response

Timeout Errors

• Default timeout: 120 seconds
• For large queries, use pagination (limit parameter)
• Consider breaking complex operations into smaller requests

Best Practices

Performance Optimization

Use Pagination

• Default limit: 500 records per request
• Always paginate when totalCount > limit
• Use filters to reduce result sets when possible

Filter Before Fetching

• Apply filters at the API level rather than filtering client-side
• Use specific filters (IDs, dates) when possible
• Combine multiple filters to narrow results

Request Optimization

• Batch related queries when possible
• Cache frequently accessed data
• Use getById methods when you know the ID

Security

• Never commit tokens to version control
• Use environment variables for sensitive data
• Rotate tokens regularly
• Implement proper error handling to avoid exposing sensitive information
• Use HTTPS for all requests

Rate Limiting

• Be mindful of API rate limits
• Implement exponential backoff for retries
• Consider implementing client-side request queuing for high-volume applications

FAQ

General

Q: What is MCP? A: Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely access external data sources and tools.

Q: Do I need to be a developer to use these tools? A: While some technical knowledge helps, many AI platforms (like Claude Desktop) provide a user-friendly interface for using MCP tools.

Q: Is my data secure? A: Yes. All requests use JWT authentication and HTTPS encryption. Your tokens are never stored on our servers.

Integration

Q: Can I use these tools with ChatGPT? A: Yes, if your ChatGPT implementation supports MCP. Check with your AI platform provider for MCP compatibility.

Q: How do I test if my setup is working? A: Try a simple query like "List all employees" or "Show me all departments" through your MCP client.

Q: What if I get authentication errors? A: Verify your JWT token is valid, not expired, and properly formatted in the Authorization header.

Support & Resources

Health Check

Check server status: GET https://mcp-alexis.simployer.com/health

Response: {"status": "ok"}

Additional Resources

• Simployer Public API Documentation 
• MCP Protocol Specification
• Related documentation: Public API MCP docs