MCP Server: When AI Agents Run Payroll Queries

What Is MCP and Why It Matters for Payroll

The Model Context Protocol (MCP) is a standardized interface between AI agents and external tools. Instead of building custom integrations for every AI model that needs to query a system, MCP provides a defined protocol: the tool declares what it can do, the AI agent calls it through a structured request, and the tool returns structured results. Think of it as a universal adapter between language models and the systems they need to interact with.

For most business software, MCP is a convenience — a cleaner way to connect AI assistants to CRM data or project management tools. For payroll, it's something more fundamental. Payroll data is uniquely sensitive (compensation, tax details, personal identifiers), uniquely structured (hierarchical tenants, period-versioned case values, statutory calculations), and uniquely consequential (wrong numbers affect people's income and tax obligations). An AI agent querying payroll needs more than API access. It needs structured tool boundaries, explicit permissions, and isolation guarantees.

That's the premise behind Payroll Engine's MCP server implementation. It doesn't expose a generic database query interface or a natural-language-to-SQL bridge. It provides a curated set of tools — each with a defined input schema, output schema, and permission requirement — that let AI agents ask specific payroll questions and get precise, structured answers.

This distinction matters because payroll is a domain where precision is non-negotiable. An AI assistant that "summarizes" payroll data by paraphrasing numbers is dangerous. An AI agent that retrieves exact wage type values through a structured tool call and presents them accurately is useful. MCP enables the latter by keeping the boundary between data retrieval and data presentation explicit.

Two Servers: Read-Only (OSS) and Write (Pro)

Payroll Engine ships two MCP server implementations, and the split between them is the most important architectural decision in the design.

PayrollEngine.Mcp.Server — Read-Only, Open Source

The open-source MCP server provides 29 read-only tools under the MIT license. It can query tenants, employees, case values, available cases for data entry, payrun results, wage type results, lookups, collectors, regulations, and more. It cannot create, modify, or delete anything. It uses the stdio protocol — no HTTP server, no open ports, no network exposure. It's part of the broader payroll compliance infrastructure that treats payroll as an embeddable platform, not a standalone application.

This server is safe to deploy with any AI agent. A misconfigured prompt, a hallucinating model, or an adversarial input cannot cause data modification. The worst case is that the agent retrieves data it shouldn't see — which is handled by the permission model (discussed below). But it cannot alter a payrun result, change an employee's salary, or delete a tenant.

PayrollEngine.Mcp.Server.Pro — Write Operations, Commercial

The commercial MCP server extends the read-only base with write operations and consolidation tools. It can create employees, set case values, conduct AI-driven case input dialogs, trigger payrun jobs, and execute cross-tenant consolidation queries. These are powerful operations that directly affect payroll processing.

The Pro server is not open source because write operations in payroll require controlled deployment. An AI agent that can trigger a payrun job or modify an employee's tax class needs to operate within an explicit approval workflow, audit trail, and permission boundary. Making these tools freely available without the surrounding operational controls would be irresponsible.

Why the Split Matters

The read/write split reflects a fundamental principle: reading payroll data is a query; writing payroll data is an action with consequences.

When an AI agent calls GetPayrunResults, it retrieves information. The payroll system's state is unchanged. The agent can call the tool ten times with different parameters and nothing is affected. When an AI agent calls CreatePayrunJob (Pro), it initiates a calculation that produces legally binding results. That's a fundamentally different category of operation, and it deserves a fundamentally different deployment model.

For providers evaluating the MCP server, this means the open-source read-only server is the starting point. Deploy it, connect it to your AI agents, and let them query payroll data. When you need write operations — triggering forecast jobs from a dashboard, automated onboarding flows, budget scenario comparisons — the Pro server is available with the appropriate operational controls.

Tool Architecture

The MCP server isn't a monolithic application. It's built on a layered architecture that separates infrastructure from implementation, making it extensible and independently testable.

PayrollEngine.Mcp.Core

The foundation is a NuGet package that provides the MCP infrastructure: the ToolBase abstraction, request isolation, permission model, input validation, and error handling. Every MCP tool inherits from ToolBase, which enforces a consistent pattern: validate inputs, check permissions, execute the query, return structured results.

Request isolation means each tool invocation is independent. There's no shared state between calls, no session that accumulates context, no side effects from one query that affect the next. This is essential for AI agent usage, where the sequence and frequency of tool calls is unpredictable.

PayrollEngine.Mcp.Tools

The 28 read-only tools are packaged as a separate NuGet library. Each tool has a defined name, description, input schema (JSON), and output schema. The tools cover the full breadth of Payroll Engine's data model:

Each tool returns structured data — not formatted text. When an AI agent calls GetWageTypeResults, it receives a JSON array of wage type identifiers and values, not a paragraph describing the results. The AI agent is responsible for formatting, summarizing, or comparing the data. The tool just delivers it accurately.

The Tool Contract

Every tool declares its interface through a schema that the AI agent can inspect before calling it. The schema specifies required and optional parameters, their types, and validation constraints. For example, GetPayrunResults requires a tenant identifier and a payrun job identifier; it optionally accepts a period filter and employee filter.

This schema-first design means AI agents can reason about which tool to call and what parameters to provide before making the request. A well-designed AI agent workflow doesn't guess at tool parameters — it reads the schema, maps the user's question to the appropriate tool and parameters, and makes a precise call.

Use Cases

The MCP server's value becomes concrete when you consider what AI agents can do with structured payroll access. Here are five scenarios that illustrate the range:

Provider Dashboard: "Show me total employer cost for DE tenants in Q1"

A provider running German payroll for 50 client companies wants a quarterly overview. Without MCP, this requires a custom report, a database query, or manual extraction from the web application. With MCP, an AI agent calls GetTenants (filtered to DE), then GetPayrunResults for each tenant's Q1 payrun jobs, aggregates the employer cost wage types (WT 7020), and presents the result — as a table, a comparison, or a natural-language summary.

The agent makes structured calls, receives structured data, and does the aggregation. No custom report development. No SQL. The data stays in the payroll system; only the query results flow to the agent.

Compliance Check: "Did any employee exceed the BBG KV/PV ceiling this month?"

Beitragsbemessungsgrenze (contribution ceiling) breaches need attention — they affect social security calculations and can indicate data entry errors. An AI agent calls GetPayrunResults for the current period, filters for employees where the KV/PV assessment base exceeds the ceiling value (retrieved via GetLookupValues from the data regulation), and reports the exceptions.

This is a query that a human would run by exporting data to a spreadsheet. The MCP server makes it a conversational request.

Case Input Dialog: "Add a new employee"

With the Pro server, the chat itself becomes the data entry interface. When a user says "Add a new employee," the AI agent calls GetAvailableCases (OSS) to discover which cases are relevant — Employment, Salary, Address, BankAccount. It then calls BuildCase (Pro) on the selected case to retrieve the full field structure: names, value types, time types, mandatory flags, default values, and any related sub-cases. Armed with this schema, the agent asks the user exactly the right questions — nothing more, nothing less — and submits the completed case change via CreateCaseChange (Pro).

No custom form. No frontend development. The regulation defines the fields; the AI conducts the dialog; the payroll engine persists the result. When the regulation changes — a new mandatory field is added, a field becomes conditional — the AI dialog adapts automatically, because it reads the schema at runtime rather than rendering a hardcoded form.

Debugging: "Why is this employee's Kirchensteuer zero?"

A payroll operator notices that an employee's church tax is zero despite being in a state that levies Kirchensteuer. Instead of manually tracing the calculation, they ask the AI agent. The agent calls GetCaseValues for the employee (checking Konfession and Bundesland), GetWageTypeResults for the Kirchensteuer wage type, and GetPayrunJobResults for the full calculation trace. It identifies that the employee's Konfession is set to "keine" — no church membership — which correctly results in zero Kirchensteuer. Mystery solved in seconds, not minutes.

Budget Forecasting: Scenario Comparison

With the Pro server, an AI agent can trigger forecast payrun jobs — non-binding calculations that don't affect the legal payroll. A provider can ask: "What's the employer cost impact if we give a 3% raise to all employees in the NL tenant?" The agent modifies case values in a forecast context, runs a forecast job, compares the results to the current legal payrun, and reports the delta. Multiple scenarios can run in parallel.

This turns payroll forecasting from a spreadsheet exercise into an interactive conversation — with calculations running through the actual payroll engine, not an approximation model.

AI Context: Teaching LLMs About Payroll

An MCP server provides tools. But an AI agent also needs to understand the domain it's querying. If an agent doesn't know what a "wage type" is, or how Payroll Engine's tenant model works, or what a payrun job produces, it can't use the tools effectively — even if the tool schemas are perfectly documented.

That's the purpose of the AI Context packages: structured documentation designed for LLM consumption, providing the domain knowledge that makes MCP tool usage effective.

PayrollEngine.AiContext (Public, OSS)

The open-source AI Context package provides structured documentation about Payroll Engine's data model, API, and core concepts. It covers tenants, employees, cases, case fields, wage types, collectors, payrolls, payruns, payrun jobs, regulations, lookups, and reports. Each concept is documented with its relationships, typical usage patterns, and the MCP tools that access it.

This isn't API reference documentation. It's context documentation — written specifically so that an LLM can build an accurate mental model of the system. When an AI agent receives a question about payroll results, the context helps it understand that results are organized by payrun job, that each job produces wage type results and collector results, and that the relevant MCP tool is GetPayrunResults with the job identifier.

PayrollEngine.AiContext.Pro (Commercial)

The commercial context package extends the public version with regulation development documentation. It covers how country regulations are structured, how wage types use No-Code actions and Low-Code expressions, how data regulations version statutory values, and how integration tests verify compliance. This context is aimed at the "Regulator" role — payroll consultants and developers who build and maintain regulations.

Context, Not Training Data

An important distinction: AI Context is runtime context, not training data. It's not used to fine-tune a model or train it on Payroll Engine. It's provided to the model at query time — alongside the MCP tool schemas — to help it understand the domain during a specific interaction.

This means the context is always current. When Payroll Engine's data model evolves — a new field on the employee object, a new tool in the MCP server — the context documentation is updated alongside it. There's no lag between the system's capabilities and the AI agent's understanding of them.

It also means no payroll data is used for training. The AI Context contains structural documentation about the platform — "employees have case values, case values have time types" — not actual employee records, salary figures, or tax calculations. The distinction between platform documentation and payroll data is absolute.

Security and Isolation

Payroll data is among the most sensitive information an organization handles. Connecting AI agents to that data requires a security model that accounts for the unique risks of LLM-driven access.

stdio Protocol: No Open Ports

Both MCP servers use the stdio (standard input/output) protocol. The server runs as a local process, communicates through stdin/stdout pipes, and exposes no network endpoints. There's no HTTP server to misconfigure, no API gateway to leave open, no port to accidentally expose to the internet.

This design choice is deliberate. Payroll MCP servers are meant to be attached to specific AI agent processes — a Cursor IDE session, a backend automation service, a controlled dashboard application. They are not meant to be network-accessible services. The stdio protocol enforces this by architecture, not by configuration.

Per-Tool Permission Model

Each MCP tool declares its required permission level. Read-only tools like GetEmployee and GetPayrunResults require read access. Write tools in the Pro server — CreatePayrunJob, SetCaseValue — require write access. Consolidation tools that query across tenants require cross-tenant access.

The permission model is enforced at the tool level, not the server level. This means a deployment can grant an AI agent read access to employee data but not to payrun results, or read access to all data but write access to nothing. The granularity matches the operational reality: different AI agent use cases need different access levels.

Read-Only as the Default

The open-source server is read-only by design. This isn't a limitation — it's a security posture. The most common MCP use cases (querying results, checking compliance, debugging calculations, generating reports) are read operations. Making read-only the default means the majority of AI agent deployments never need write access, and therefore never carry the risk of AI-initiated data modification.

When write access is needed, the Pro server is deployed with explicit configuration. The deployment decision — "this AI agent can modify payroll data" — is a conscious choice with a defined scope, not an accidental capability that comes with installing the MCP server.

No Training on Payroll Data

MCP is a tool execution protocol, not a data pipeline. When an AI agent calls GetPayrunResults, the result flows from the Payroll Engine backend through the MCP server to the agent's context window. It's used for the current interaction and subject to the AI provider's data retention policies.

The MCP server does not cache results, aggregate queries, or build usage datasets. It doesn't send payroll data to third-party services, analytics platforms, or model training pipelines. Each tool call is stateless: the result is returned and the server retains nothing.

For organizations subject to GDPR, data residency requirements, or financial services regulations, this architecture means the payroll data stays where it is — in the Payroll Engine backend, in the organization's infrastructure. The MCP server is a lens, not a pipeline.

Isolation per Request

Each MCP tool invocation is isolated. There's no session state that accumulates across calls, no context that leaks between requests, and no shared memory between tool invocations. If an AI agent calls GetEmployee for employee A and then GetPayrunResults for employee B, the second call has no awareness of the first.

This isolation prevents a class of vulnerabilities where accumulated context could lead to unauthorized data access. An agent that queries one tenant's data in one call cannot leverage that context to access another tenant's data in the next call. Each invocation is independently authenticated and authorized.

For multi-tenant deployments — a provider running payroll for multiple client companies — this isolation is essential. Each client's data is accessed through separate, permission-checked tool calls. The MCP server enforces the same tenant boundaries as the underlying Payroll Engine backend.