Skip to main content
Glama

MCP FactorialHR

The definitive Model Context Protocol server for FactorialHR

License: MIT CI codecov TypeScript Node.js npm version npm downloads Official MCP Registry t4dhg/mcp-factorial MCP server MCP Compatible Audited by AddonAudit

A comprehensive Model Context Protocol (MCP) server that provides AI assistants like Claude with full access to FactorialHR. Manage employees, teams, time off, projects, training, recruiting, and more - all with built-in safety guardrails.

Why This MCP Server?

  • Context-Optimized: 14 hierarchical tools (117 operations) with 88% less context usage than individual tools

  • Full CRUD Operations: Create, read, update, and delete across all major entities

  • Safety Guardrails: High-risk operations require explicit confirmation

  • Audit Logging: All write operations are logged with timestamps and context for debugging

  • Enterprise Ready: Built for companies who need AI integration with proper controls

Related MCP server: myteam-mcp

Features

Hierarchical Tool Discovery (v8.0.0+)

The MCP server uses a hierarchical tool structure for optimal context usage. Instead of 124 individual tools, you get 14 category-based tools with an action parameter.

Tool

Description

Actions

factorial_discover

Discover available categories

-

factorial_employees

Employee management

list, get, search, create, update, terminate

factorial_teams

Team management

list, get, create, update, delete

factorial_locations

Location management

list, get, create, update, delete

factorial_contracts

Contract/salary data

list, get_with_employee, by_job_role, by_job_level

factorial_time_off

Leave management

10 actions

factorial_attendance

Shifts and registro horario

14 actions incl. clock_in, audit, log_range

factorial_documents

Document management

8 actions (downloads require OAuth2 - see below)

factorial_job_catalog

Job roles/levels

list_roles, get_role, list_levels

factorial_projects

Project management

16 actions for projects, tasks, workers, time

factorial_training

Training management

12 actions for trainings, sessions, enrollments

factorial_work_areas

Work area management

list, get, create, update, archive, unarchive

factorial_ats

Applicant tracking

17 actions for recruiting

factorial_payroll

Payroll data (read-only)

6 actions

Example Usage:

// List all employees
factorial_employees({ action: 'list', page: 1, limit: 50 });

// Get a specific employee
factorial_employees({ action: 'get', id: 123 });

// Search employees
factorial_employees({ action: 'search', query: 'john' });

// Create a leave request
factorial_time_off({
  action: 'create',
  employee_id: 123,
  leave_type_id: 1,
  start_on: '2026-02-01',
  finish_on: '2026-02-05',
});

// Discover available actions for a category
factorial_discover({ category: 'employees' });

124 Operations Across 14 Categories

Category

Operations

Employees

list, get, search, create, update, terminate

Teams

list, get, create, update, delete

Locations

list, get, create, update, delete

Time Off

list_leaves, get_leave, list_types, get_type, list_allowances, create, update, cancel, approve, reject

Attendance

list, get, create, update, delete, clock_in, clock_out, status, gaps, audit, log_range, log_days, list_edit_requests, create_edit_request

Projects

16 operations for projects, tasks, workers, time records

Training

12 operations for trainings, sessions, enrollments

Work Areas

list, get, create, update, archive, unarchive

ATS

17 operations for job postings, candidates, applications, hiring stages

Payroll

list/get supplements, tax identifiers, family situations (read-only)

Documents

8 operations for folders, documents, and downloads (⚠️ downloads require OAuth2)

Job Catalog

list_roles, get_role, list_levels (read-only)

Contracts

list, get_with_employee, by_job_role, by_job_level (read-only)

Time Off Approvals

A leave request is decided by its own approver. In Factorial that is the time-off approver on the employee's record (timeoff_manager_id), and a company API key is permitted to approve or reject any request, so "pending" and "pending for me" are different sets that look the same from the API. The server keeps them apart:

  • list_leaves and get_leave add timeoff_manager_id, timeoff_manager_name and routed_to_me to every leave. routed_to_me is true or false when it can be told, and null when the server does not know who you are.

  • list_leaves with pending_for_me: true returns exactly the requests awaiting your decision: pending leaves of the employees whose approver is you, across every page.

  • approve and reject read the leave and its employee afresh and refuse, naming the actual approver, when the leave is routed to someone else, when the employee has no approver on record, or when the server does not know who you are (in which case no override is accepted either). Nothing is written.

  • A decision is recorded in Factorial under whoever made it. Under a company API key that would be the key's account rather than you, so approve and reject are refused before anything is read, with or without an override, until you log in. An operator who accepts that attribution can set FACTORIAL_ALLOW_COMPANY_KEY_APPROVALS=true; the confirmation step and the result of each decision then say who it was recorded under.

  • To decide a request on another approver's behalf, pass override_approver: true and an override_reason saying who asked and why. The first call writes nothing and returns a preview and a confirmation_token; repeating the call with the token executes it, and the override and its reason are recorded on the audit entry. The override is for having been asked to act for that approver, not for a request that merely happens to be pending.

You are the employee who logged in. Under a company API key alone you are the employee in FACTORIAL_EMPLOYEE_ID, which has to be configured because the API cannot supply it: api_public/credentials reports no employee for a company API key. The approver is read from the employee record; this server does not model multi-step approval flows configured in Factorial.

Attendance and Registro Horario

Factorial asks employees to record their working hours day by day. factorial_attendance lets Claude do that, for one day or for a whole month, and for any employee the API key can see.

Times are HH:MM in the company's local time, exactly as Factorial shows them; Factorial applies them in the company zone and the server never converts between zones. Records written by this server carry source: "api", so they are distinguishable from live clocks in Factorial's own activity log.

A write's declared working time (date, clock_in, clock_out) is independent of its entry metadata: Factorial stamps created_at, updated_at and in_source/out_source with when and how the record was entered, and those cannot be set or changed through the API. Every create, update, clock_in, clock_out, and every bulk preview and result, states the declared working time and says this once.

Action

What it does

status

Whether the employee is clocked in and since when. Always prints the configured identity.

clock_in, clock_out

Live clocking at the current time, or, given date and time (HH:MM company local), a declared moment for someone who forgot to clock. A declared moment in the future is refused before any request is sent. A declared clock_out is refused if nothing is open, or if the moment precedes the open shift's start.

gaps

Workdays in a date range where the contract expects more hours than were tracked. Weekends, bank holidays and full-day leave are excluded.

audit

One row per calendar day in a range: day type, expected and tracked hours, leave cover, the shifts on record and a status (complete, missing, short, over, weekend, bank_holiday, on_leave, half_day_leave, no_contract_data, future). missing is nothing on record; short is some hours tracked but under expected by more than the tolerance, shown with its delta. A signed-off date is marked separately and is closed for writing; create_edit_request is how it gets corrected. The header gives expected (bank holidays and leave at full contract minutes) alongside workday expected (what tracked hours should actually meet). statuses restricts the summary to a given set. format is summary (default, only the days needing attention), table (every day) or json (the ledger). The starting point for reconciling what was clocked against what should have been.

log_range

Apply a daily pattern (segments) to every workable day in a range. Skips weekends, bank holidays, days the contract expects 0 minutes, approved leave, future dates, signed-off dates, exclude_dates, and any segment overlapping an existing shift.

log_days

Write an explicit list of days with their segments, for migrating from another platform. Only refuses future dates, approved leave, signed-off dates and overlaps, so a Saturday someone worked can be written.

list, get, create, update, delete

Individual shift records. list needs start_on and end_on (or ids, or updated_at); Factorial ignores paging on this endpoint, so paging is client-side. fields: "compact" on list returns a smaller payload (date, clock_in, clock_out, minutes, in_source); get returns the complete record.

list_edit_requests, create_edit_request

Factorial's route for correcting a signed-off day, since hours cannot be written onto a reviewed date directly. Filing a request notifies whoever approves timesheets, so create_edit_request is previewed and token-gated even for the configured identity.

// Find the missing days first
factorial_attendance({ action: 'gaps', start_on: '2026-03-01', end_on: '2026-03-31' });

// Preview a month of split days; nothing is written yet
factorial_attendance({
  action: 'log_range',
  start_on: '2026-03-01',
  end_on: '2026-03-31',
  segments: [
    { clock_in: '09:00', clock_out: '14:00' },
    { clock_in: '15:00', clock_out: '18:00' },
  ],
});
// -> "Plan for <name> (<id>) ... 20 days to write, 40 shift records, 160h ... confirmation_token: <token>"

// Same call plus the token writes it
factorial_attendance({ action: 'log_range', /* same arguments */ confirmation_token: '<token>' });

// Afterwards, reconcile the month
factorial_attendance({ action: 'audit', start_on: '2026-03-01', end_on: '2026-03-31' });

"Today" for the future-date rule is the date in the zone of the machine running the server, so run it in the company's zone or accept that the boundary day may be off by one. Bank holidays come from the company's own calendar in Factorial (worked_times.day_type), so no holiday list is needed. Approved leave is read from timeoff/leaves; pass skip_leave: false when the source system is right and Factorial's leave record is stale. Half-day leave days are left out of log_range and named in the preview; write the worked half with log_days.

Nobody clocks in at exactly 09:00 every day, and a month of identical entries is the one pattern a real registro never shows. Pass jitter_minutes (5 to 10 is sensible) to log_range or log_days and each written time varies by up to that many minutes from your pattern, within the day; segments never cross each other. Pass variation_minutes for a different kind of variation: it shifts a whole day by one deterministic offset so the start time drifts from day to day, which jitter_minutes cannot produce because it only varies segments within a day. Both are derived from the employee, the date and (for jitter) the segment, so the preview lists the exact times that will be written, the confirmation token binds to them, and a retry recognises its own earlier records. The records still carry source: "api"; these options make reconstructed hours realistic, they do not disguise where they came from.

Every gaps, audit and bulk-write preview starts with a Data read line: how many days of the window have contract data, and how many leave and shift records were read. Reads follow Factorial's pagination to the end, so a window of any length is complete; a date the API returned nothing for is reported as no_contract_data and never written, rather than passed off as a day that was not workable. Those dates normally precede the start of employment. If they do not, the read was incomplete and the result should not be trusted.

Signed-off periods. Once a date's timesheet has been reviewed in Factorial, it is closed for writing; a shift write on it is refused with a 403. audit reads attendance/reviews alongside the other facts and marks such dates signed off before anything is written; log_range and log_days skip them the same way they skip a weekend or an approved leave day. The way to correct a signed-off day is create_edit_request, which files a request that whoever approves timesheets then decides on; list_edit_requests reads what has been filed. Filing a request is previewed and token-gated even for the configured identity, because it notifies a person.

A date that does not exist, such as 2026-02-30, is refused rather than silently rolled forward to the next valid date; a real leap day such as 2024-02-29 is accepted normally.

Auditing a month. Run audit for the range first. A day within tolerance_minutes (default 15) of its expected total counts as complete, so realistic clock-ins and jittered backfills do not read as shortfalls. Compare the ledger with what you know locally (your calendar, another time-tracking system, days you actually worked on a holiday), then fix the differences: log_range or log_days for missing days, delete or update for wrong records, and audit again to confirm every workday reads complete.

Five prompts wrap these workflows for the user, and a guide resource documents them for the model; see 5 MCP Prompts and factorial://guides/registro-horario. Some clients (Claude Code included) surface a prompt only as a slash command the human invokes, with no way for the model itself to read one, so each prompt's procedure is also published as a resource at factorial://prompts/<name>.

Set FACTORIAL_EMPLOYEE_ID to your own employee id so that employee_id can be omitted. Writes aimed at anyone else, and every bulk write, require a confirmation token; see Safety & Security.

6 MCP Resources

Resource URI

Description

factorial://org-chart

Complete organizational hierarchy (Markdown)

factorial://guides/registro-horario

How to audit, fill and maintain a registro horario with this server (Markdown)

factorial://employees/directory

Employee directory by team (Markdown)

factorial://locations/directory

Location directory with employee counts (Markdown)

factorial://timeoff/policies

All leave types and policies (JSON)

factorial://teams/{team_id}

Team details with member list (JSON, templated)

factorial://prompts/{name}

The procedure text of an attendance prompt, readable without invoking it (Markdown)

5 MCP Prompts

Prompts are procedures the user invokes (in Claude Code they appear as /mcp__factorial__<name> slash commands). The attendance prompts pre-read the data the procedure starts from and state the exact tool calls that follow, so a small model can carry the workflow through. A prompt never writes anything itself; writes go through factorial_attendance and its confirmation gate.

Prompt

Arguments

What it does

attendance_audit

start_on, end_on, employee_id (all optional)

Runs the audit (default: this month to today, FACTORIAL_EMPLOYEE_ID) and asks for a read-only report: expected vs tracked, missing and over days by month, data-coverage warnings.

attendance_fill

segments (required), start_on, end_on, employee_id, observations, jitter_minutes

Reads the gaps and hands over the exact log_range call with the parsed pattern, then the preview, human confirmation, token, retry and verification steps. segments is "09:00-14:00, 15:00-18:00".

attendance_today

segments (required), employee_id, observations, jitter_minutes

Reads today's status and decides: nothing on weekends, holidays, leave, open shifts or complete days; otherwise log_days for today, confirmed in the same session for the configured identity only.

attendance_reconcile

known_absences (required), start_on, end_on, employee_id

Runs the audit and reports only the days that disagree with a stated list of known absences (days off, sick days, trips). Read-only.

attendance_fill_days

days (required), employee_id, observations, jitter_minutes

Enters registro horario for a list of explicit dates, each with its own daily pattern, as one log_days call: preview, human confirmation, token, retry and verification. days is [{"date":"2026-03-02","segments":"09:00-14:00, 15:00-18:00"}].

summarize_team

team_id

Team summary with members and roles.

time_off_report

employee_id

Time off report for an employee: allowances and recent leaves.

Running the daily record on a schedule. MCP has no scheduler, so the schedule lives in the client. In Claude Code, /schedule creates a routine that invokes attendance_today with your pattern, and /loop repeats it while a session is open; any cron can run claude -p with the prompt as its input. The prompt writes only when today is a workday with nothing tracked, and only for the employee in FACTORIAL_EMPLOYEE_ID; it reports one line either way. The record it produces is a legal document of hours worked, so the pattern you schedule must be the hours you actually work, and the day you do not work needs a leave record or a manual correction.

Architecture Features

  • Safety Guardrails: High-risk operations (terminate, delete) marked for confirmation

  • Audit Logging: All write operations logged in-process with timestamps and context

  • Caching: In-memory TTL-based caching (configurable by resource type)

  • Pagination: All list operations support pagination

  • Retry Logic: Exponential backoff with rate limit handling

  • Validation: Runtime validation with Zod schemas

Quick Start

1. Add to your MCP configuration

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"]
    }
  }
}

2. Set your API key

Create a .env file in your project root:

FACTORIAL_API_KEY=your-api-key-here

Or pass it directly in the MCP config:

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"],
      "env": {
        "FACTORIAL_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Start using it!

Once configured, ask Claude things like:

  • "Who's on the Engineering team?"

  • "Create a new employee John Smith"

  • "Which time off requests are waiting for my approval?"

  • "Create a new project called Q1 Marketing Campaign"

  • "Enroll Sarah in the Leadership Training program"

  • "Show me all open job postings"

  • "What candidates applied for the Senior Developer position?"

Getting an API Key

You'll need a FactorialHR API key to use this MCP server. Here's how to get one:

  1. Log in to FactorialHR as an administrator

  2. Go to Settings → API keys

  3. Click the "New API key" button

  4. Give your key a descriptive name (e.g., "Claude Code" or "MCP Server")

  5. Click Create - your API key will be displayed

  6. Copy the key immediately - it's only shown once and cannot be retrieved later

  7. Add the key to your .env file or MCP configuration

Important: API keys have full access to your FactorialHR data and never expire. Store them securely, never commit them to version control, and rotate them periodically.

Acting as Yourself: User Login

Factorial records every write under the credential that made it. A company API key acts as the company, not as a person: Factorial's documentation says its requests are "authenticated on behalf of the company", so an approval, a shift or an edit made with it is recorded under the key's account, whoever asked for it. A user login acts as one employee: its requests are "performed on behalf of a specific employee" and are limited by that employee's permission group.

This server can hold both. When you have logged in, every write goes out as you, and reads keep using the API key when one is configured, because the key sees the whole company and a user token sees only what you may. Without a login the server still works with the API key alone, and then:

  • every confirmation step and every result of a write says that Factorial records it under the company API key's account, not under you;

  • approve and reject on leave requests are refused, unless the operator sets FACTORIAL_ALLOW_COMPANY_KEY_APPROVALS=true.

A write never falls back from the login to the API key. If the login has expired and cannot be refreshed, the write fails with a message telling you to log in again.

Step 1: Create an OAuth application

An administrator does this once per company, in Factorial under Settings → Advanced configuration → OAuth applications:

  • Client type: Public (authorization code with PKCE, no client secret). A confidential application also works; set FACTORIAL_OAUTH_CLIENT_SECRET as well.

  • Redirect URI: https://t4dhg.github.io/mcp-factorial/callback/. Factorial's production environment accepts https redirect addresses only. This one is a static page that shows the address it was opened with, so that you can paste it into the terminal; it makes no request and stores nothing. The address does reach the host that serves the page, as any web address does, so what protects the login is PKCE and not the page: the code in the address cannot be redeemed without a verifier that never leaves the command. You can host the same page on an address of your own and set FACTORIAL_OAUTH_REDIRECT_URI to it.

  • Scopes: one per area you use, for example Employees, Documents, Time off, Time tracking, and Approvals for deciding leave requests. Scopes never grant more than the person logging in is already allowed to do.

Set the application's client id where the server reads its configuration:

FACTORIAL_OAUTH_CLIENT_ID=your-client-id

Step 2: Log in

Each person runs this once, in a terminal:

npx -y @t4dhg/mcp-factorial login

It opens Factorial in your browser. Sign in as yourself and approve the access; Factorial sends you to the redirect page, which shows an address to copy. Paste it into the terminal, and the command checks which employee the token belongs to and stores the login. The address holds a one-time code that is of no use without the verifier the command kept to itself. It refuses a company token, since writes made with one would not carry your name.

The login is stored in ~/.config/mcp-factorial/login.json (or $XDG_CONFIG_HOME/mcp-factorial/login.json, or %APPDATA%\mcp-factorial\login.json on Windows), outside any repository and readable by you only. Access tokens last one hour and are refreshed automatically; each refresh replaces the refresh token, and the new one is written back to the file. Several running servers can share one login.

Where Factorial accepts loopback addresses, as its demo environments do, you can skip the pasting: register http://127.0.0.1:53682/callback on the application, set FACTORIAL_OAUTH_REDIRECT_URI to it, and the command listens there and receives the redirect itself.

Two more commands:

npx -y @t4dhg/mcp-factorial whoami   # who writes are recorded under; shows no credential
npx -y @t4dhg/mcp-factorial logout   # revoke the login and remove it from this machine

What changes once you are logged in

  • You are the employee who logged in. FACTORIAL_EMPLOYEE_ID is not needed and is ignored.

  • Writes carry Authorization: Bearer with your token and never the API key.

  • Factorial applies your own permissions. A write you are not allowed to make is refused by Factorial with a 403, and the error says to check your permission group and the application's scopes.

  • Document downloads use the login too, so the three FACTORIAL_OAUTH_* download variables below are not needed.

FACTORIAL_AUTH_MODE chooses between the two credentials: auto (the default) writes with the login when there is one and with the API key otherwise; oauth never writes with the API key, so nothing can be written until someone logs in; api_key ignores a stored login.

OAuth2 Setup (Required for Document Downloads)

Document download actions (download_payslips, download) require OAuth2 authentication. This is a Factorial API limitation - the download endpoint does not accept API key authentication.

The simplest way to satisfy it is the user login above: once you are logged in, downloads work with nothing else to configure. The steps below are the older route, which supplies a refresh token through the environment. Factorial retires a refresh token once it has been used and the server cannot write the new one back to your configuration, so this route needs a fresh token after the server restarts.

Note: You need admin access in Factorial to create OAuth applications.

Step 1: Create an OAuth2 Application

  1. Go to: https://api.factorialhr.com/oauth/applications

  2. Click "New application"

  3. Fill in:

    • Redirect URI: http://localhost:8080/callback (or any URL you can access)

    • Confidentiality: Yes (server application)

    • Scopes: Select the scopes you need:

      • Required for downloads: Documents, Employees

      • Recommended for full MCP functionality: Contracts, Payroll, Payroll supplements, Time off, Shift management, Trainings, Recruitment, Company locations, Job catalog

  4. Save and note your Client ID and Client Secret

Step 2: Get Authorization Code

Open this URL in your browser (replace YOUR_CLIENT_ID):

https://api.factorialhr.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8080/callback&response_type=code
  • Log in and authorize the app

  • You'll be redirected to your callback URL with ?code=AUTHORIZATION_CODE

  • Copy that code from the URL (it expires quickly, so proceed to step 3 immediately)

Step 3: Exchange Code for Tokens

Run this curl command (replace placeholders):

curl -X POST 'https://api.factorialhr.com/oauth/token' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'code=AUTHORIZATION_CODE' \
  -d 'grant_type=authorization_code' \
  -d 'redirect_uri=http://localhost:8080/callback'

You'll get a response with access_token and refresh_token. Save the refresh_token.

Step 4: Configure MCP Server

Add OAuth2 credentials to your MCP configuration:

{
  "mcpServers": {
    "factorial": {
      "command": "npx",
      "args": ["-y", "@t4dhg/mcp-factorial"],
      "env": {
        "FACTORIAL_API_KEY": "your-api-key",
        "FACTORIAL_OAUTH_CLIENT_ID": "your-client-id",
        "FACTORIAL_OAUTH_CLIENT_SECRET": "your-client-secret",
        "FACTORIAL_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Or add to your .env file:

FACTORIAL_API_KEY=your-api-key
FACTORIAL_OAUTH_CLIENT_ID=your-client-id
FACTORIAL_OAUTH_CLIENT_SECRET=your-client-secret
FACTORIAL_OAUTH_REFRESH_TOKEN=your-refresh-token

Important Notes

  • The MCP server refreshes access tokens using the refresh token, and keeps using the newest one for as long as it runs

  • A refresh token works once: after a restart the one in your configuration has already been used, so repeat steps 2-3, or use the user login, which stores each new token

  • If document downloads suddenly stop working, your refresh token has likely expired or been used

Use Cases

For Managers

  • Create and manage team structures

  • See the time off requests routed to you, and approve or reject them

  • Assign employees to projects

  • Track project time records

  • Monitor training enrollments

For HR

  • Onboard new employees with full data entry

  • Manage job postings and recruiting pipeline

  • Track candidate applications through hiring stages

  • Generate org structure analysis

  • Manage training programs and enrollments

For Developers

  • Build AI workflows that need employee context

  • Create custom Claude integrations

  • Automate HR processes with AI assistance

  • Generate reports and analytics

Configuration Options

Environment Variable

Description

Default

FACTORIAL_API_KEY

Your FactorialHR API key. Optional once you have logged in; reads then see only what you may

Required

FACTORIAL_API_VERSION

API version

2026-07-01

FACTORIAL_EMPLOYEE_ID

Your employee id: who you are for leave approvals; default target and ungated identity for attendance. Ignored once you have logged in

-

FACTORIAL_AUTH_MODE

auto, oauth or api_key: which credential writes use (see user login)

auto

FACTORIAL_ALLOW_COMPANY_KEY_APPROVALS

true lets approve and reject run under a company API key, recorded under the key's account

false

FACTORIAL_OAUTH_REDIRECT_URI

Redirect URI registered on the OAuth application, for login

https://t4dhg.github.io/mcp-factorial/callback/

FACTORIAL_OAUTH_SCOPES

Space-separated scopes to request at login; unset leaves the choice to the application

-

FACTORIAL_TOKEN_FILE

Where the login is stored

~/.config/mcp-factorial/login.json

FACTORIAL_TIMEOUT_MS

Request timeout (ms)

30000

FACTORIAL_MAX_RETRIES

Max retry attempts

3

DEBUG

Enable debug logging

false

FACTORIAL_OAUTH_CLIENT_ID

OAuth application client id, for login and for downloads

-

FACTORIAL_OAUTH_CLIENT_SECRET

OAuth application client secret; only for a confidential application

-

FACTORIAL_OAUTH_REFRESH_TOKEN

OAuth2 refresh token (older route for downloads; not needed once you have logged in)

-

Safety & Security

Who a Write Is Recorded Under

Every write is recorded in Factorial under the credential that made it: you, once you have logged in, or the company API key's account otherwise. Under a company API key the server says so wherever it matters:

  • the description of every tool that can write states the rule, so a client reads it before it acts;

  • every confirmation prompt and every confirmation-token preview says that Factorial will record the action under the company API key's account, not under you;

  • the result of every write that went out with the key says that it was recorded that way, including a bulk write that failed part of the way through;

  • approve and reject on leave requests are refused outright unless FACTORIAL_ALLOW_COMPANY_KEY_APPROVALS=true.

A token previewed under one credential does not confirm a write under another.

Operations That Require Confirmation

The following operations require explicit confirmation (confirm: true). Called without it, the tool returns a warning describing the impact and makes no change. Risk is classified per operation in src/write-safety.ts; everything below is gated regardless of whether it is rated high or medium:

  • factorial_employees({ action: 'terminate' }) - Terminates an employee

  • factorial_teams({ action: 'delete' }) - Permanently deletes a team

  • factorial_locations({ action: 'delete' }) - Permanently deletes a location

  • factorial_projects({ action: 'delete' }) - Permanently deletes a project

  • factorial_projects({ action: 'delete_task' }) - Deletes a project task

  • factorial_projects({ action: 'delete_time' }) - Deletes a time record

  • factorial_projects({ action: 'remove_worker' }) - Deletes an employee's assignment to a project

  • factorial_attendance({ action: 'delete' }) - Deletes a shift record

  • factorial_time_off({ action: 'cancel' }) - Cancels a leave request

  • factorial_time_off({ action: 'reject' }) - Rejects a leave request

  • factorial_training({ action: 'delete' }) - Deletes a training program and its enrollments

  • factorial_training({ action: 'delete_session' }) - Deletes a training session

  • factorial_training({ action: 'unenroll' }) - Deletes an employee's training enrollment

  • factorial_ats({ action: 'delete_posting' }) - Deletes a job posting and its applications

  • factorial_ats({ action: 'delete_candidate' }) - Permanently deletes a candidate

  • factorial_ats({ action: 'delete_application' }) - Permanently deletes an application

Operations Gated by a Confirmation Token

Attendance writes are gated by who they target and how many records they touch, which a per-operation policy cannot express. A first call writes nothing and returns a preview that names the person, the dates and the totals, plus a confirmation_token valid for fifteen minutes and bound to exactly that plan. Repeating the call with the token executes it; if the plan changed in between (someone wrote a shift), the token is refused and a new preview is issued. confirm: true cannot bypass this gate, because there is no token to pass on a first call.

Gated whenever the target is not you (the employee who logged in, or the configured FACTORIAL_EMPLOYEE_ID), and always when the server does not know who you are:

  • factorial_attendance({ action: 'create' }) - Creates a shift for another person

  • factorial_attendance({ action: 'update' }) - Updates another person's shift (the shift is fetched first to learn whose it is)

  • factorial_attendance({ action: 'delete' }) - Deletes another person's shift, in addition to confirm: true

  • factorial_attendance({ action: 'clock_in' }) - Clocks another person in

  • factorial_attendance({ action: 'clock_out' }) - Clocks another person out

Always gated, whatever the target, because volume is its own hazard:

  • factorial_attendance({ action: 'log_range' }) - Writes one or more shift records per workable day in a range

  • factorial_attendance({ action: 'log_days' }) - Writes an explicit list of days

  • factorial_attendance({ action: 'create_edit_request' }) - Files a request to change a timesheet, which notifies a person, so it is gated even for the configured identity

Gated whenever a leave is decided on another approver's behalf, which is the only way to decide a leave that is not routed to you (see Time Off Approvals):

  • factorial_time_off({ action: 'approve' }) - With override_approver: true and an override_reason, approves a leave routed to someone else

  • factorial_time_off({ action: 'reject' }) - With override_approver: true and an override_reason, rejects a leave routed to someone else; the token stands in for confirm: true

Re-running a bulk call after a partial failure is safe against its own earlier writes: the planner re-reads existing shifts and skips whatever overlaps. It does not protect against another writer between the read and the writes.

Document Downloads

Document names come from Factorial metadata rather than from the caller, so downloads treat them as untrusted:

  • The name is reduced to a single path segment, so a name containing path separators cannot redirect the download outside output_dir.

  • Control characters are dropped and over-long names are shortened, keeping the extension.

  • Nothing is ever overwritten. If the target name is already taken, the file is saved as name (1).ext, name (2).ext and so on. This protects existing files in output_dir and stops two documents that share a name from collapsing into one.

Downloads still write wherever you point output_dir, so point it at a directory meant for downloads rather than a source tree or your home directory.

Read-Only Categories

Some categories are intentionally read-only for security:

  • Payroll: Supplements, tax identifiers, family situations

  • Documents: Folder and document metadata (download tools available for payslips and documents)

  • Contracts: Historical contract data

Response Optimization

Document and contract list operations return summary format by default to prevent token overflow:

Documents (factorial_documents({ action: 'list' })):

  • Returns: id, name, folder_id, employee_id, mime_type (5 fields)

  • Default limit: 100 documents per page

  • For full details: Use factorial_documents({ action: 'get', id: X }) for complete metadata

Contracts (factorial_contracts({ action: 'list' })):

  • Returns: id, employee_id, job_title, effective_on (4 fields)

  • Default limit: 100 contracts per page

All list operations accept page and limit parameters for pagination control.

Audit Logging

All write operations (create, update, delete, approve, reject) are recorded with:

  • Timestamp

  • Operation type

  • Entity type and ID

  • Changes made

  • Success or failure, and duration

  • For a leave decided on another approver's behalf: the approver, the caller and the reason given

Scope of this log. The trail is held in memory in the running server process, capped at the most recent 1000 entries, and is not exposed through any tool or resource. It is lost when the process exits. Set DEBUG=true to have each entry written to the server's stderr, which is the only way to retain it today. It is a debugging aid, not a compliance record: if you need a durable, queryable audit trail, use FactorialHR's own activity log as the system of record.

Development

Use Node.js 22 or 24 for development; .nvmrc selects Node 24. The installed server requires Node.js 20+.

# Clone the repository
git clone https://github.com/t4dhg/mcp-factorial.git
cd mcp-factorial

# Install dependencies
npm ci

# Enable local pre-commit checks
npm run setup:hooks

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Format
npm run format

# Run locally
FACTORIAL_API_KEY=your-key npm start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

Project Structure

The codebase is organized into domain-based modules for maintainability:

src/
├── schemas/           # Zod schemas by domain
│   ├── employees.ts   # Employee, Team, Location, Contract schemas
│   ├── time-off.ts    # Leave, LeaveType, Allowance, Shift schemas
│   ├── projects.ts    # Project, Task, Worker, TimeRecord schemas
│   ├── training.ts    # Training, Session, Membership schemas
│   ├── ats.ts         # JobPosting, Candidate, Application schemas
│   └── ...
├── api/               # API functions by domain
│   ├── employees.ts   # listEmployees, getEmployee, createEmployee, etc.
│   ├── time-off.ts    # listLeaves, createLeave, approveLeave, etc.
│   ├── projects.ts    # listProjects, createProject, etc.
│   └── ...
├── auth/              # User login: token store, refresh, login command, write attribution
├── tools/             # MCP tool registrations by domain
│   ├── employees.ts   # factorial_employees tool registration
│   ├── time-off.ts    # factorial_time_off tool registration
│   ├── index.ts       # Server setup, discovery tool, resources, prompts
│   └── ...
├── cli.ts             # login, logout and whoami commands
├── index.ts           # Entry point (re-exports from tools/)
├── api.ts             # Re-exports from api/
└── schemas.ts         # Re-exports from schemas/

Adding a new feature:

  1. Add schemas to src/schemas/{domain}.ts

  2. Add API functions to src/api/{domain}.ts

  3. Add tool actions to src/tools/{domain}.ts

  4. Update src/schemas/index.ts, src/api/index.ts exports if needed

  5. Run npm test to verify

Troubleshooting

"Your Factorial login has expired or was revoked"

The stored login could not be refreshed. Run npx -y @t4dhg/mcp-factorial login again. Until you do, nothing is written: the server does not fall back to the API key for a write. npx -y @t4dhg/mcp-factorial whoami shows the current state.

"Refused: this server is using a company API key"

approve and reject are refused under a company API key, because Factorial would record the decision under the key's account instead of under you. Log in, or see Time Off Approvals for the setting that allows it.

API Key Not Working

  • Ensure the API key has appropriate permissions

  • Check if the key has been revoked or expired

  • Verify the key is set correctly in environment variables

Rate Limiting

The server implements exponential backoff for rate limits. If you're hitting limits frequently:

  • Reduce request frequency

  • Use pagination with smaller page sizes

  • Enable caching by avoiding cache-busting parameters

Missing Data

  • hired_on field: The FactorialHR API may not populate this for all employees

  • Team membership: Some employees may not be assigned to teams

  • Empty responses: Check if the resource exists in your Factorial account

Document Downloads Not Working

Document downloads require OAuth2 authentication. This is a Factorial API limitation - the download endpoint does not accept API key authentication.

If you see an error like:

"Document download requires OAuth2 authentication"

You need to set up OAuth2 credentials. See OAuth2 Setup above.

Note: With the older environment-variable route, a refresh token works once. If downloads stop working after a restart, re-authorize and get a new refresh token, or switch to the user login.

"Document with ID X not found" Error

The Factorial API's individual document endpoint (GET /documents/{id}) has limitations accessing employee-specific documents. This happens because:

  1. list_documents with employee_ids filter correctly returns all employee documents

  2. get_document by ID cannot access those same documents individually

Workaround: Use download_payslips action instead of download action. The download_payslips action uses the document metadata from the list operation directly, bypassing the problematic individual GET endpoint:

// This works - uses document list internally
factorial_documents({
  action: 'download_payslips',
  employee_id: 123,
  output_dir: '/path/to/downloads',
});

FAQ

Q: Does this expose salary/payroll data? A: Payroll data (supplements, tax identifiers, family situations) is available read-only. No write operations for payroll are supported.

Q: Can Claude modify data in Factorial? A: Yes! Full CRUD operations are available for employees, teams, locations, time off, projects, training, and recruiting. High-risk operations are clearly marked.

Q: How is data cached? A: Data is cached in-memory with TTLs: employees (5 min), teams (10 min), locations (15 min), contracts (3 min).

Q: What FactorialHR API version is used? A: Version 2026-07-01 by default. Override with FACTORIAL_API_VERSION environment variable. Since that version every Factorial identifier (id and *_id fields) is a string, not a number; treat them as opaque strings.

Q: Can Claude fill in my registro horario? A: Yes. Set FACTORIAL_EMPLOYEE_ID, run gaps to see the missing days, then log_range with your daily segments. The first call returns a preview and a token; the second call writes. See Attendance and Registro Horario.

Q: Are write operations logged? A: Yes, every write is recorded by the audit module with a timestamp, entity, changes, and outcome. The log lives in memory in the running process (last 1000 entries) and is not retrievable through the MCP interface, so treat it as a debugging aid rather than a compliance record. See Audit Logging.

Factorial API Quirks and Limitations

The FactorialHR API has some design patterns that differ from typical REST APIs. This MCP server handles these automatically, but understanding them helps when debugging or extending:

Data Location Quirks

Data

Expected Location

Actual Location

Impact

Team membership

On Employee object (team_ids)

On Team object (employee_ids)

Use list_teams to find an employee's teams

Job role assignment

On Employee object (job_role_id)

In Contract object (job_catalog_role_id)

Use get_employee_with_contract for role info

Salary information

On Employee object

In Contract object (salary_amount, salary_frequency)

Use get_employee_with_contract for salary

Job title

On Employee object

In Contract object (job_title)

May be null if not set in Factorial

Endpoint Quirks

Endpoint

Quirk

Workaround

GET /employees/{id}

May return 404 for valid employees

Server falls back to listing all and filtering

GET /documents/{id}

May return 404 for employee-specific documents

Use download_payslips which bypasses this

GET /contracts?employee_id=X

Filtering unreliable

Server fetches all and filters client-side

Empty results

Returns {"errors": null} instead of `{"data": []}

Server handles both formats

Document download URLs

Requires OAuth2 (API key does not work)

Configure OAuth2 credentials for downloads

Field Availability

Some fields may be null even when you expect data:

  • job_title: Only populated if set in employee's contract

  • manager_id: Only populated if reporting structure is configured

  • seniority_calculation_date: Use this instead of the non-existent hired_on field

  • Document metadata (name, mime_type, size_bytes): May be null for some documents

Salary Data

Salary information is available in the Contract entity, not the Employee entity:

salary_amount: number (in cents, e.g., 7000000 = €70,000)
salary_frequency: 'yearly' | 'monthly' | 'weekly' | 'daily' | 'hourly'

Use get_employee_with_contract to retrieve employee data with their latest salary information.

Best Practices

  1. To get an employee's job role: Use get_employee_with_contract instead of get_employee

  2. To find employees by role: Use list_employees_by_job_role with a job role ID

  3. To find an employee's teams: Query list_teams and check employee_ids arrays

  4. For salary data: Always use contract endpoints, not employee endpoints

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © Taig Mac Carthy


Built with the Model Context Protocol by Anthropic

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for PrismHR, enabling AI agents to automate payroll, benefits, compliance, and billing tasks with verified-schema tools and scope-gated consent.
      18
      34 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the HR platform 'МояКоманда' that enables AI assistants to access and interact with HR data like employees, teams, calendar, absences, requests, knowledge base, surveys, and more via its REST API.
      MIT