Headless HCM
Headless HCM: your HR system as a data engine for AI agents
Headless HCM is an HR system whose data and process logic sit behind an API, so the system’s own screen is one way of working rather than the only one.
The architecture matters now because the request for employee data increasingly comes from an AI agent acting on someone’s behalf, not from a person clicking through views. We have been moving MintHCM in this direction for several releases, first without the label and now deliberately.
In short
Headless HCM is an HR system whose data and processes are available through an API, so the interface is one of several ways to use it. MintHCM exposes its modules through an API and an MCP server, so an AI assistant can query HR data under the same permissions as a person. The MCP server is available today. The other three layers, including the AI Agents module, are at an early stage of work. The interface stays, but it is no longer the only channel for work.
On this page
- What is headless HCM?
- Why is the interface no longer the only way HR work gets done?
- Where can an AI agent connect to MintHCM?
- What does the MintHCM MCP server do?
- What is the MintHCM AI Agents module?
- What is AG-UI, and does MintHCM support it?
- What is Web MCP, and when does it matter?
- How is an AI agent configured in MintHCM?
- How does MintHCM control what an AI agent can see?
- How does headless HCM differ from a classic HCM?
- What does MintHCM not do yet?
- How do you tell whether an HR system is ready for AI agents?
- Frequently asked questions
- How can you test this on your own data?
What is headless HCM?
Headless HCM is a human capital management system in which the data, the process logic and the permissions sit behind an API, and the interface is one client of that API. The term predates the current wave of AI. In computing, headless describes software that runs without a graphical interface, such as a server with no screen or a browser with no window. The “head” is the presentation layer. The idea reached business software through headless CMS platforms and later through e-commerce.
An online shop is an easy example. One sales process runs underneath, and several interfaces sit on top of it: one for phones, one for desktop, sometimes a separate one built for a single large client. With many screens, the value lies in a well-documented API rather than in any particular view. In HR the stakes are higher, because a personnel process lives for years while the ways people work with it change every few.
In an HR system, that separation looks like this:
The backend
Holds what is difficult and expensive to rebuild: the employee data model, organisational structure, recruitments and applications, onboarding and offboarding, appraisals, working time, permissions and process rules.
The interface
Is one client of that backend. An important one, because it is where people supervise and decide, but not the only one.
Every other client
An integration, a script or an AI agent receives the same data under the same rules and has no way around the system.
Headless HCM keeps its screen. What changes is that the system does not need the interface in order to operate. The difference shows up when something changes. In a system built around the screen, a new way of working means a new screen and a rollout to everyone who uses it. In a headless system it means a new API client, and everything else stays as it is.
Why is the interface no longer the only way HR work gets done?
For years, HCM vendors competed on the number of clicks: how many screens stand between a specialist and an issued amendment, whether a leave request can be approved from a phone, what the absence calendar looks like. That still matters, but it is no longer the only question.
Part of the work has moved into conversation. An HR specialist with an AI assistant can ask which onboardings are running past their deadline instead of opening five views, and can ask how many candidates have been waiting on a decision for more than two weeks instead of building a report. Tasks that used to take a dozen clicks and knowledge of where everything lives become a question in plain language. The interface stays, and the work divides into two modes.
Stays in the interface
Single-record work
Entering data, approving a request and running an interview. People want the surrounding context and take responsibility for the decision.
Moves to the agent
Cross-cutting work
Questions spanning many records, summaries, searching for exceptions and repetitive document analysis. It is faster there.
This split is the reason we changed priorities in MintHCM. A single interface for everyone is no longer the main goal. An orderly data model, a complete API, an MCP server and the further layers through which AI agents work with the system now matter more. We still improve the screen, but when the choice is between a better icon and an agent correctly understanding how a recruitment is structured, we choose the second.
Where can an AI agent connect to MintHCM?
“The system has AI” can mean very different things, from a chat window added to a login screen to a mechanism that analyses candidate documents on its own. So instead of promising AI, we describe four places where an AI agent connects to MintHCM. They are separate solutions and differ in where the agent runs and who starts the exchange. Only the MCP server is available today. The other three layers are at an early stage of work.
MCP server and MCP App
Where the agent runs
Outside, on the assistant’s side
What it gives the user
Working with MintHCM from your own assistant, with interactive MintHCM views inside the chat
Server in production, interactive layer being reworked
AI Agents module
Where the agent runs
Inside MintHCM, with no person involved
What it gives the user
Agents triggered on records: CV analysis, summaries, reaction to a status change
Early stage of work, internal only
AG-UI
Where the agent runs
Inside MintHCM, in conversation with the user
What it gives the user
A built-in chat that not only answers but switches views and opens records
On hold, early research, no code
Web MCP
Where the agent runs
In the user’s browser
What it gives the user
A browser agent understands MintHCM’s public pages
Proof of concept outside the system
The MCP server is the only layer available today and takes up most of this page. The other three are at an early stage of work, so read them as direction, not as something to plan a deployment around. The layers differ most in the direction of flow.
In MCP, MintHCM supplies tools and views to an agent running somewhere else. In AG-UI it is the reverse: the MintHCM application hands an agent the tools to drive the application itself. In the AI Agents module there is no conversation at all: the agent starts itself when a record is saved.
What does the MintHCM MCP server do?
Model Context Protocol is a standard way for an AI assistant to discover which tools are available to it and how to use them. The MintHCM MCP server exposes the system’s modules through that protocol: searching and counting records, reading fields and relationships, creating and updating data, running reports and reading its own process documentation, so the agent knows both the structure of the database and how work is done in the system.
For example, a question that would otherwise require building a report becomes a single sentence: which onboardings started in the last thirty days are still open, and whose tasks are outstanding in them. The agent assembles the answer from several calls (finding the onboardings, querying related tasks, filtering by date) and returns a list.
MCP App: interactive views inside the chat
MCP App goes beyond text. A classic MCP server returns data, and the agent describes it in words. With MCP App, MintHCM returns a fragment of its own interface into the conversation, and that fragment sends the user’s actions back to the agent’s context. In practice:
A list you can act on
You write “show my meetings this week” and get a list with checkboxes rather than a paragraph. You tick four out of ten, write “close them”, and the agent knows which ones, because your selection went back into its context.
Charts drawn by MintHCM
Charts are rendered on the MintHCM side. The agent receives a finished visualisation instead of building one from scratch, and it knows what the chart contains, so you can ask follow-up questions about it.
Search forms from the system
Search forms behave as they do in the system, only inside the chat, with no need to explain to the agent what a field is called.
Among the HR systems with an MCP server that we have tested, none returns an interactive view like this; they stop at a text reply.
What is the MintHCM AI Agents module?
The MCP server needs someone to ask a question. The AI Agents module does not. An agent is a configuration record in the system, and it runs by itself when a condition on a record is met: on save, on a status change, when an attachment appears. The module is at an early stage of work and has not been released publicly yet.
Unlike a chat inside the system, the module involves no conversation. It runs a process. The agent’s configuration (when it runs, what data it sees, what it does) is stored like any other system setting, and every run leaves a complete trace. The configuration and the trace are described below.
HR examples of what the module is built for
CV analysis
An application receives a new note with a file. The agent reads the document and writes back a summary and an assessment against the position’s requirements. The file reaches the model as an attachment, not as pasted text.
Reaction to a status transition
An application moves to “after entry interview” and the agent prepares a note tidying up what was agreed and proposing the next step.
Cross-record summaries
An agent on a recruitment record gathers the related applications and returns an overview for whoever is running it.
What is AG-UI, and does MintHCM support it?
AG-UI reverses the direction. In MCP, MintHCM hands tools to an agent running outside. Here the MintHCM application defines the tools an agent can use inside it: draw a chart, open the employee view, switch the list to this filter.
The intended scenario: you have a dashboard open, you tell the built-in chat you are looking for a candidate from a particular recruitment, and the system switches the view and shows the record. The chat is no longer a separate box beside the system and becomes a way of navigating it.
Status: concept stage. We keep the topic in view alongside the development of the built-in chat. As long as an agent can call MCP, most of the benefit is already available, so AG-UI fits best as an addition to the chat: if the chat is being built anyway, it costs little compared with a separate project.
What is Web MCP, and when does it matter?
Web MCP means markup in the page source that lets an agent working in a browser understand what it is looking at instead of guessing from layout. Work on it is at an early stage: so far we have only a proof of concept, built outside MintHCM.
This is the least urgent of the four layers: wherever an agent can call MCP, Web MCP adds nothing. It makes sense in public areas that an agent reaches without logging in. The clearest example is published job adverts: a candidate’s personal assistant opens the posting and needs to understand the requirements, the form of employment and how to apply, rather than interpret the arrangement of buttons.
There is a second reason to keep this path open. Many companies have no centralised AI environment. People in those organisations use whatever is built into their systems and their browser, and will keep working that way for a long time. They are a different audience from a company that has rolled out an assistant for the whole team.
How is an AI agent configured in MintHCM?
This section describes how the mechanism works in practice. An agent in MintHCM is a record of type AIAgentDefinition, and every run of it is written to AIExecution. The configuration has three parts, and they behave differently when something goes wrong. The difference is intentional.
| Element | What it is | Behaviour on error |
|---|---|---|
| execution_condition | The condition deciding whether the agent runs on this record | Fail-closed: a broken condition blocks the run |
| context_definition | A description of the data sent to the model: record fields, related records, attachments | Fail-open: an unavailable fragment is skipped and the agent carries on |
| Execution log | The full input context in AIExecution.initial_input | Always written, including when a file could not be delivered |
The first row protects against an agent running where it should not. The second protects against one missing relationship halting an entire personnel process.
Three kinds of data in the context
The entry_record type covers fields on the record the agent runs on. The related type covers related records, with filters and a limit that defaults to ten. The attachment type covers files, one by default, with a size limit of roughly 20 MB. A node that returns nothing is dropped and does not reach the model as an empty value.
The change operator
It compares a field’s value before and after the save, so an agent can run exactly on a transition: not when the status equals X, but when the status has just become X. In HR processes this is the difference between one reaction and a reaction on every later save of the record.
An example from the documentation
An agent reads CVs attached to a record as notes, filtered by a name starting with “CV” and limited to three files. The files go to the model as attachments, not as text pasted into a prompt.
How does MintHCM control what an AI agent can see?
A headless architecture carries a clear risk. Once data leaves through an API, permissions and the record of changes matter more than before. With personnel data such as salaries, appraisals and candidate documents, this is a practical concern. Three mechanisms in MintHCM address it.
A user’s permissions apply to the agent
Where a context definition does not list fields, the system falls back to the permissions of the account the agent runs under: no access to a module means no data. Where the author of a definition lists fields explicitly, that list is a deliberate decision, and responsibility for the scope of data sits with the agent’s configuration. For attachments, access is verified every time, whichever field the definition points at.
A file’s type comes from its contents
A file’s type is determined from its contents, not from what it declares. A declared type can be changed through the API, so it proves nothing.
Every run leaves a comparable trace
In the AI Agents module, exactly the context the model received lands in the execution log, not a summary of it, so two runs can be placed side by side to see what changed between them.
This trace is what makes a conversation with your legal team or data protection officer possible. The question “on what basis did this agent write that” has an answer in the system, not in the memory of whoever configured it.
How does headless HCM differ from a classic HCM?
The difference shows up in seven places, from how the system is reached to what is recorded when an agent works in it.
| Classic HCM | Headless HCM | |
|---|---|---|
| Main point of access | The system’s interface | The API, with the interface as one client |
| Role of the interface | The only channel for getting things done | A layer for supervision and decisions |
| AI agent | An add-on attached to the screen | A client of the system like any other |
| A new way of working | A new screen, rolled out to everyone | A new API client, everything else unchanged |
| Integrations | Point solutions, often built for one case | One data contract for every consumer |
| Permissions | Enforced on the screen | Enforced in the data layer, so they apply to agents too |
| Record of activity | Record change history | Change history plus the agent’s input log |
The permissions row is the most important one. A system that enforces permissions only on the screen stops enforcing them as soon as the first agent connects, because an agent never uses the screen.
What does MintHCM not do yet?
The headless approach in MintHCM is still in progress. These are the current limits to know before making a decision.
AG-UI is not available
It is at an early stage of work, linked to the expansion of the built-in chat, so it cannot be deployed yet.
Web MCP was tested outside MintHCM
We have a proof of concept; we do not have markup in the system. Today we see the point of this layer only in public areas.
The AI Agents module is not yet publicly released
It is at an early stage of work; until it ships, the MCP server is the layer to plan around.
We are still tidying the data model
An agent is only as good as the description of the data it receives. Part of our headless work consists of cleaning up field names, dropdowns and relationships, so that a question asked in words reaches the right data.
Introducing agents will not be easy in every organisation. If personnel processes are undocumented and the data sits in four places at once, an agent will expose those problems instead of solving them.
How do you tell whether an HR system is ready for AI agents?
Five questions to ask any vendor, whether or not MintHCM is on your list:
Is every operation available in the interface also available through the API?
If some processes can only be carried out from the screen, an agent will not carry them out at all.
Where are permissions enforced?
On the screen, or in the data layer. Only in the second case does an agent inherit a user’s limits.
Can you see exactly what the model received?
The answer should be a stored input context that you can reconstruct afterwards.
Can an agent be configured without a developer?
The trigger condition and the scope of data as configuration in the system, not as an implementation project.
Is process documentation available to the agent?
An agent that knows only the table structure does not know how recruitment works at your company.
If the answer to most of these is “no” or “on the roadmap”, agents will be an add-on in that system rather than a way of working. That does not make the system bad.
Frequently asked questions
How is headless HCM different from an ordinary HCM with an API?
Every modern system has an API. In headless HCM the API is the main point of access rather than an addition to the screen, and permissions and process rules apply through it. The measure is how much of the work can be done without the interface.
Does headless HCM mean a system with no interface?
No. It means a system whose operation does not depend on one particular interface. MintHCM has a full interface and we continue to develop it. Its status changed from the only channel for work to one of several.
What is MCP in an HR system?
Model Context Protocol is a standard way for an AI assistant to discover available tools and use them. The MintHCM MCP server exposes the system’s modules through it, so an assistant can search records, count them, read relationships or run a report without a purpose-built integration.
Will an AI agent see data the user has no access to?
No. The agent runs under a specific account’s permissions, and where a context definition lists no fields, MintHCM checks those permissions, so no module access means no data. Where an author lists fields explicitly, that author sets the scope. Attachment access is checked every time.
Does the AI Agents module require a developer?
The module is designed so that an agent’s configuration (its trigger condition and the scope of its data) is a record in the system, not an implementation. A developer would be needed only to extend the mechanism itself in unusual ways. The module is at an early stage of work and has not been released publicly yet.
Where should you start when preparing an HR system to work with agents?
Start with the data model and process documentation, before choosing a language model. An agent uses what the system has named and ordered, and cannot use what employees carry in their heads.
How can you test this on your own data?
MintHCM is open source. You can install it, connect your own assistant through the MCP server and see on your own records whether talking to an HR system shortens the work. This is the most reliable test, because the result depends on how well ordered your data already is.
- Try MintHCM: get the demo and run it on your own data
- Connect an assistant over MCP: how to configure the MCP server
- Read the documentation: modules, data model and agent configuration
- If you would rather see it working first, recordings of MintHCM being used through MCP are on our MintHCM YouTube channel.