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 uses the PayrollEngine.Client.Core NuGet package and communicates via stdio transport.

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. Result includes employee context (identifier, first name, last name).
list_company_case_values Company-level case values of a tenant — all company fields with start/end dates.

Case Changes

Case changes are the audit trail of data mutations: each change records who made it, in which payroll, with what reason, and which field values were affected.

Tool Description
list_employee_case_changes Audit trail of employee data mutations. Use to answer "who changed what and when". Supports OData filter and top. Result includes employee context.
list_company_case_changes Audit trail of company data mutations. Supports OData filter and top.

Payroll — Payroll Processing

Payroll execution and result analysis: payroll structure, payruns, payrun jobs, result values, preview calculations, temporal case value queries, and lookup resolution. A Payroll Specialist who needs to look up employees requires HR: Read in addition.

Structure

Tool Description
list_payrolls List all payrolls of a tenant
get_payroll Get a payroll by name
list_payruns List all payruns of a tenant
list_payrun_jobs List all payrun jobs, ordered by creation date descending. Includes period, status, employee count, and job timing. Result contains a divisions lookup (id → name) alongside the payrunJobs array.
list_payroll_wage_types Effective wage types of a payroll, merged across all regulation layers.
get_payroll_lookup_value Resolved lookup value for a given key or range value, merged across all regulation layers. Use lookupKey for exact-key lookups and rangeValue for progressive lookups (e.g. income bracket).

Results

Payroll results reflect what was calculated during payrun execution. Two complementary views are available:

Tool Description
list_payroll_result_values Flat list of all result values (wage types and collectors). Fully denormalized — each row includes employeeIdentifier, payrollName, periodName, payrunName, and jobName. Supports optional filter by employee or payroll, plus OData filter. Use for cross-employee or cross-period analysis.
get_consolidated_payroll_result All wage type results, collector results, and payrun results for one employee and one period in a single response. Use for a complete per-employee per-period overview. Result includes employee context and period boundaries.

Preview

Tool Description
get_employee_pay_preview Preview the payroll calculation for a single employee without persisting results. Returns wage type results, collector results, and payrun results. Requires McpServer:PreviewUserIdentifier to be configured.

Temporal Case Values

get_case_time_values queries case values as they were valid at a specific point in time, with three temporal perspectives:

  • Historical — set valueDate and evaluationDate to the same date to see data exactly as it was on that date, excluding later corrections.
  • Current knowledge — set only valueDate; evaluationDate defaults to today, so retroactive corrections are visible.
  • Forecast — set a forecast name and evaluationDate = valueDate to include planned future values.
Tool Description
get_case_time_values Case values valid at a specific point in time. Supports Employee, Company, and Global case types. When scoped to a single employee via employeeIdentifier, result includes employee context.

Report — Report Execution

Payroll report execution and result analysis. Reports are resolved across all regulation layers of the payroll and return one or more named result tables. Requires McpServer:PreviewUserIdentifier to be configured.

Tool Description
execute_payroll_report Execute a payroll report and return its result data set. The report is resolved across all regulation layers of the payroll. Use the parameters dictionary to pass report-specific input values (e.g. period, employee filter).

System — Administration

Tenant and user queries for cross-tenant administration and user management.

Tool Description
list_tenants List all tenants
get_tenant Get a tenant by identifier
get_tenant_attribute Get a single custom attribute of a tenant
list_users List all users of a tenant
get_user Get a user by identifier
get_user_attribute Get a single custom attribute of a user

Permissions

Each role is independently enabled or disabled per deployment.

Value Description
None Role tools are not registered — invisible to the AI agent
Read Query tools registered (default)

Role × Isolation Level

✓ = permission can be assigned (None / Read)
✗ = not applicable at this isolation level

Role MultiTenant Tenant Division Employee
HR ✓ ✓ ✓ ✓
Payroll ✓ ✓ ✓ ✗
Report ✓ ✓ ✗ ✗
System ✓ ✓ ✗ ✗

Tool × Role

Each tool belongs to exactly one role. Granting a role registers all its tools.
* = always registered, independent of role permissions.

Tool HR Payroll Report System
get_server_info * * * *
list_divisions ✓
get_division ✓
get_division_attribute ✓
list_employees ✓
get_employee ✓
get_employee_attribute ✓
list_employee_case_values ✓
list_company_case_values ✓
list_employee_case_changes ✓
list_company_case_changes ✓
list_payrolls ✓
get_payroll ✓
list_payruns ✓
list_payrun_jobs ✓
list_payroll_wage_types ✓
get_payroll_lookup_value ✓
list_payroll_result_values ✓
get_consolidated_payroll_result ✓
get_employee_pay_preview ✓
get_case_time_values ✓
execute_payroll_report ✓
list_tenants ✓
get_tenant ✓
get_tenant_attribute ✓
list_users ✓
get_user ✓
get_user_attribute ✓

Tool × Isolation Level

✓ = available
F = available, records automatically filtered to configured scope
G = available, access denied if employee is not in configured scope
✗ = not registered at this isolation level

Tool MultiTenant Tenant Division Employee
get_server_info ✓ ✓ ✓ ✓
list_divisions ✓ ✓ F F
get_division ✓ ✓ ✓ G
get_division_attribute ✓ ✓ ✓ G
list_employees ✓ ✓ F ¹ F ¹
get_employee ✓ ✓ G G
get_employee_attribute ✓ ✓ G G
list_employee_case_values ✓ ✓ G G
list_company_case_values ✓ ✓ ✓ ✓
list_employee_case_changes ✓ ✓ G G
list_company_case_changes ✓ ✓ ✓ ✓
list_payrolls ✓ ✓ F ✗
get_payroll ✓ ✓ G ✗
list_payruns ✓ ✓ F ✗
list_payrun_jobs ✓ ✓ F ✗
list_payroll_wage_types ✓ ✓ G ✗
get_payroll_lookup_value ✓ ✓ G ✗
list_payroll_result_values ✓ ✓ F ✗
get_consolidated_payroll_result ✓ ✓ G ✗
get_employee_pay_preview ✓ ✓ ✓ ✗
get_case_time_values ✓ ✓ G ² ✗
execute_payroll_report ✓ ✓ ✗ ✗
list_tenants ✓ ✓ ✗ ✗
get_tenant ✓ ✓ ✗ ✗
get_tenant_attribute ✓ ✓ ✗ ✗
list_users ✓ ✓ ✗ ✗
get_user ✓ ✓ ✗ ✗
get_user_attribute ✓ ✓ ✗ ✗

¹ Division filtering applied client-side — the backend does not support OData collection lambda expressions (divisions/any()). All employees are fetched and then filtered in memory by division membership.
² Guard applies only when employeeIdentifier is provided. Without it, Company and Global case types return all values unfiltered; Employee case type returns values for all employees without division scoping.

Persona Examples

Persona HR Payroll Report System
HR Manager Read None None None
Payroll Specialist Read Read None None
HR Business Partner Read Read None None
Controller / Analyst Read Read Read None
Report Analyst None None Read None
System Administrator None None None Read
Developer Read Read Read Read

Prerequisites

Configuration

Backend connection settings in McpServer/appsettings.json:

{
  "ApiSettings": {
    "BaseUrl": "https://localhost",
    "Port": 443
  }
}

Sensitive settings (API key) go in apisettings.json (excluded from source control):

{
  "ApiSettings": {
    "ApiKey": "your-api-key"
  }
}

IsolationLevel and role permissions in appsettings.json:

{
  "McpServer": {
    "IsolationLevel": "Tenant",
    "TenantIdentifier": "acme-corp",
    "Permissions": {
      "HR":      "Read",
      "Payroll": "Read",
      "Report":  "Read",
      "System":  "None"
    }
  }
}

For Division isolation:

{
  "McpServer": {
    "IsolationLevel": "Division",
    "TenantIdentifier": "acme-corp",
    "DivisionName": "sales"
  }
}

For Employee isolation:

{
  "McpServer": {
    "IsolationLevel": "Employee",
    "TenantIdentifier": "acme-corp",
    "EmployeeIdentifier": "mario.nunez@acme.com"
  }
}

For payrun preview and report execution (get_employee_pay_preview, execute_payroll_report), configure a service account user that exists in the target tenant:

{
  "McpServer": {
    "PreviewUserIdentifier": "mcp-service@acme.com"
  }
}

All settings can also be provided as environment variables using the __ separator:

McpServer__IsolationLevel=Tenant
McpServer__TenantIdentifier=acme-corp
McpServer__DivisionName=sales
McpServer__EmployeeIdentifier=mario.nunez@acme.com
McpServer__PreviewUserIdentifier=mcp-service@acme.com
McpServer__Permissions__HR=Read
McpServer__Permissions__Payroll=Read
McpServer__Permissions__Report=Read
McpServer__Permissions__System=None
ApiSettings__BaseUrl=https://your-backend
ApiSettings__Port=443

MCP Client Setup

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "payroll-engine": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "path/to/McpServer/PayrollEngine.McpServer.csproj",
        "--no-launch-profile",
        "--no-build"
      ],
      "env": {
        "DOTNET_ENVIRONMENT": "Development",
        "ApiSettings__BaseUrl": "https://localhost",
        "ApiSettings__Port": "443",
        "AllowInsecureSsl": "true"
      }
    }
  }
}

Docker

docker run --rm -i \
  -e ApiSettings__BaseUrl=https://your-backend \
  -e ApiSettings__Port=443 \
  ghcr.io/payroll-engine/payrollengine.mcpserver

Example Prompts

List all tenants
Show me the employees of StartTenant
What case values does mario.nunez@foo.com have in StartTenant?
What changed in the employee data of mario.nunez@foo.com in January 2026?
What wage types are effective in the CH-Monthly payroll of CH.Swissdec?
What was the salary of all employees as of Dec 31, 2024?
Show me all payroll results for Müller in March 2026
What is the tax rate for an income of 85000 in the TaxRates lookup?
What would the payroll look like for Müller in April 2026?
Run the MonthlyPayslip report for the CH-Monthly payroll

License

MIT License — free for personal and commercial use.