Payroll Engine MCP Server

MCP (Model Context Protocol) server for the Payroll Engine — enables AI agents to query and analyse payroll data using natural language.

The MCP Server is read-only by design. It is an information and analysis tool; write operations are not exposed — with two exceptions: get_employee_pay_preview and execute_payroll_report execute synchronous calculations that return results without persisting anything to the database.

Overview

The MCP server exposes Payroll Engine functionality as typed tools that AI clients (Claude Desktop, GitHub Copilot, Cursor, etc.) can invoke directly. It communicates via stdio transport and is built on two libraries:

• PayrollEngine.Mcp.Core — isolation model, permission system, and ToolBase infrastructure
• PayrollEngine.Mcp.Tools — the complete set of read-only query tools

Access Control

Access is controlled by two independent dimensions:

| Dimension | Controls | Applied | |:----------|:---------|:--------| | Isolation Level | Which records are returned | At runtime, per query | | Permissions | Which tools are registered | At startup, once |

Isolation Level restricts data — a Tenant-isolated server cannot return records from another tenant regardless of which tools are active. Permissions restrict functionality — a tool that is not granted is invisible to the AI agent.

Isolation Level

Controls which records are returned at runtime. A Tenant-isolated server physically cannot return records from another tenant, regardless of which roles are active.

| Value | Description | |:------|:------------| | MultiTenant | Full access across all tenants (default) | | Tenant | All tool calls scoped to a single tenant | | Division | Scoped to a single division within a tenant. Requires TenantIdentifier and DivisionName. | | Employee | Self-service — single employee access. Requires TenantIdentifier and EmployeeIdentifier. |

Roles

Controls which tools are registered at startup. Each tool belongs to exactly one role. A tool whose role is not granted is invisible to the AI agent.

| Value | Domain | |:------|:-------| | HR | Employee master data, case values, and audit trail | | Payroll | Payroll execution, results, preview calculations, temporal case value queries, and lookup resolution | | Report | Payroll report execution and result analysis | | System | Tenant and user management |

Server — Always Available

The server tool is registered unconditionally — regardless of role permissions or isolation level.

| Tool | Description | |:-----|:------------| | get_server_info | Returns server version, active isolation level, configured scope, and role permissions. Use to verify which build is running and how it is configured. |

HR — Human Resources

Employee master data and organisational structure: who is employed, in which division, under what conditions, and how that data has changed over time. Includes the full case value history and the audit trail of all data mutations.

Organisation

| Tool | Description | |:-----|:------------| | list_divisions | List all divisions of a tenant | | get_division | Get a division by name | | get_division_attribute | Get a single custom attribute of a division | | list_employees | List employees with optional OData filter (e.g. lastName eq 'Müller') | | get_employee | Get an employee by identifier | | get_employee_attribute | Get a single custom attribute of an employee |

Case Values

Case values are the current and historical field values of an employee or company (e.g. salary, address, IBAN). The history contains all versions with their validity period.

| Tool | Description | |:-----|:------------| | list_employee_case_values | Full case value history of an employee — all fields with start/end dates

... View full README on GitHub