TalentHR MCP by usefulapi

List the company's employees from the TalentHR directory with name, e-mail, job title, department, division, location, employment status, manager id, hire date and phone. Paged (limit max 100): use next_offset to continue. Filter by location, department, division or employment status (emp_state) with `filter`; get the ids from talenthr_get_directory_filters. Use `custom_fields` to add extra field slugs (from the company's custom fields). Returns personal data; summarize only what the user asked for.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Rows per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Row offset, 0-based (default 0). Use next_offset from the previous reply.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    },
    "custom_fields": {
      "description": "Comma-separated custom field slugs to include, e.g. address,city,custom-field-001.",
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z0-9_-]+(,[a-z0-9_-]+)*$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the valid filter options (departments, divisions, locations, employment statuses) with their ids, to build the `filter` argument of talenthr_list_employees and talenthr_get_calendar.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one employee's profile: birth date, hire and termination date, personal e-mail, work phone, address, nationality, gender, job title, department, division, location, role, seniority and custom fields. Contains sensitive personal data (it can include the SSN); only fetch it when the user asked about that person.

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The employee id (from talenthr_list_employees)."
    }
  },
  "required": [
    "employee_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one employee's job information: employment status history, manager records, job records (title, department, location over time), compensation records and benefits. Compensation is sensitive; only fetch it when the user asked.

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The employee id (from talenthr_list_employees)."
    }
  },
  "required": [
    "employee_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List all current employees with their manager (reports_to_employee_id), job title and role, to answer who reports to whom.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List all departments of the company with their ids (the ids are what talenthr_list_employees filters and employee records refer to).

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List all divisions of the company with their ids (the ids are what talenthr_list_employees filters and employee records refer to).

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List all locations (with address and remote flag) of the company with their ids (the ids are what talenthr_list_employees filters and employee records refer to).

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List all job titles of the company with their ids (the ids are what talenthr_list_employees filters and employee records refer to).

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the time off types (vacation, sick leave, ...) with id, yearly budget, whether approval is needed and whether it is paid. The id is needed to book a request with talenthr_create_time_off_request.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List one employee's time off requests (dates, type, days, approved or pending, canceled). Paged: use next_offset to continue. A request with approved=null is still pending.

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The employee id (from talenthr_list_employees)."
    },
    "limit": {
      "description": "Rows per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Row offset, 0-based (default 0). Use next_offset from the previous reply.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "sort": {
      "description": "Column to sort by: id, timeoff_type_name, created_at.",
      "type": "string",
      "enum": [
        "id",
        "timeoff_type_name",
        "created_at"
      ]
    }
  },
  "required": [
    "employee_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one employee's time off budgets per type and cycle: budget, original budget, used days and accrual figures, i.e. how many days they have left. Optionally limit to the current cycle (active) or one cycle id.

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The employee id (from talenthr_list_employees)."
    },
    "active": {
      "description": "true = only the currently active time off cycle.",
      "type": "boolean"
    },
    "time_off_cycle_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "Limit to one time off cycle id."
    }
  },
  "required": [
    "employee_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Who is off when: employees with their time off requests and the holidays for a date range. Without end_date the range runs to the end of the start month (max 2 years). Without a filter it includes every employee (also terminated). Filter with keys time_off (pending, approved), department, division, location, emp_state and time_off_type (e.g. time_off=pending,approved;department=6), or one employee with employee_id.

{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "description": "First day, yyyy-mm-dd."
    },
    "end_date": {
      "description": "Last day, yyyy-mm-dd (default: end of the start month).",
      "type": "string"
    },
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "Only this employee's calendar."
    },
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    }
  },
  "required": [
    "start_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company holidays of a year (current year by default) with date and who they apply to.

{
  "type": "object",
  "properties": {
    "year": {
      "description": "Year, e.g. 2026 (default: this year).",
      "type": "integer",
      "minimum": 1990,
      "maximum": 2100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's benefits with category, cost, dates and who they are required for. Optional `filter` with keys location, department, division, job_title, emp_state and employee (e.g. location=36;emp_state=1,2).

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the benefits one employee has (category, cost, start and end date).

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The employee id (from talenthr_list_employees)."
    }
  },
  "required": [
    "employee_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's assets (laptops, phones, subscriptions, memberships) with status, category, serial number, cost, purchase and warranty dates. Paged: use next_offset to continue. `search` matches name, description or category; `filter` takes status and category ids (e.g. status=1,2;category=19).

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Rows per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Row offset, 0-based (default 0). Use next_offset from the previous reply.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    },
    "sort": {
      "description": "Column to sort by: created_at, name, category, location, department, division, used_by, serial_number, warranty_end_date.",
      "type": "string",
      "enum": [
        "created_at",
        "name",
        "category",
        "location",
        "department",
        "division",
        "used_by",
        "serial_number",
        "warranty_end_date"
      ]
    },
    "order": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the assets (inventory and memberships) assigned to one employee. Paged: use next_offset to continue.

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The employee id (from talenthr_list_employees)."
    },
    "limit": {
      "description": "Rows per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Row offset, 0-based (default 0). Use next_offset from the previous reply.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "sort": {
      "description": "Column to sort by: assing_date, name, category, type, serial_number.",
      "type": "string",
      "enum": [
        "assing_date",
        "name",
        "category",
        "type",
        "serial_number"
      ]
    },
    "order": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "required": [
    "employee_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the company's job positions (open and closed) with title, status, location, department, publish date and the hiring steps. The id is used to list a position's applicants.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the applicants of one job position with contact data, current hiring step and whether they are disqualified. Paged: use next_offset to continue. `search` matches first name, last name and e-mail.

{
  "type": "object",
  "properties": {
    "job_position_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The job position id (from talenthr_list_job_positions)."
    },
    "limit": {
      "description": "Rows per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Row offset, 0-based (default 0). Use next_offset from the previous reply.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "sort": {
      "description": "Column to sort by: name, created_at.",
      "type": "string",
      "enum": [
        "name",
        "created_at"
      ]
    },
    "order": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "required": [
    "job_position_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List every candidate across all job positions with contact data and the number of applications. Paged: use next_offset to continue. `search` matches first name, last name and e-mail; `starred_only` returns only the starred candidates (the talent pool).

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Rows per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Row offset, 0-based (default 0). Use next_offset from the previous reply.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "starred_only": {
      "type": "boolean"
    },
    "sort": {
      "description": "Column to sort by: name, created_at.",
      "type": "string",
      "enum": [
        "name",
        "created_at"
      ]
    },
    "order": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one candidate with contact data, description, CV info and all applications with the hiring step each one is in. The application ids are used by talenthr_create_applicant_note.

{
  "type": "object",
  "properties": {
    "applicant_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The applicant id (from talenthr_list_applicants)."
    }
  },
  "required": [
    "applicant_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Headcount per month over a period (total and optionally grouped by gender, location, department, division, ...), plus the current headcount.

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "pattern": "^(l12m|(19|20)\\d{2})$",
      "description": "Reporting period: l12m (last 12 months) or a 4-digit year (the current or the previous calendar year). Alternatively pass start_date and end_date (max 36 months)."
    },
    "start_date": {
      "description": "Custom range start, yyyy-mm-dd (use with end_date instead of period).",
      "type": "string"
    },
    "end_date": {
      "description": "Custom range end, yyyy-mm-dd.",
      "type": "string"
    },
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    },
    "group_by": {
      "description": "Break the headcount down by this dimension.",
      "type": "string",
      "enum": [
        "location",
        "department",
        "division",
        "gender",
        "age",
        "seniority"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Hires, terminations and attrition rate per month over a period.

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "pattern": "^(l12m|(19|20)\\d{2})$",
      "description": "Reporting period: l12m (last 12 months) or a 4-digit year (the current or the previous calendar year). Alternatively pass start_date and end_date (max 36 months)."
    },
    "start_date": {
      "description": "Custom range start, yyyy-mm-dd (use with end_date instead of period).",
      "type": "string"
    },
    "end_date": {
      "description": "Custom range end, yyyy-mm-dd.",
      "type": "string"
    },
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Approved, non-canceled time off summarized per month and per weekday, split by time off type, for a period.

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "pattern": "^(l12m|(19|20)\\d{2})$",
      "description": "Reporting period: l12m (last 12 months) or a 4-digit year (the current or the previous calendar year). Alternatively pass start_date and end_date (max 36 months)."
    },
    "start_date": {
      "description": "Custom range start, yyyy-mm-dd (use with end_date instead of period).",
      "type": "string"
    },
    "end_date": {
      "description": "Custom range end, yyyy-mm-dd.",
      "type": "string"
    },
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List time tracking entries across all employees (start, end, duration, tags) for a period or date range. Paged: use next_offset to continue. working_now=true lists only running timers. Needs a key whose user may see everyone's time tracking.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Rows per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Row offset, 0-based (default 0). Use next_offset from the previous reply.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "period": {
      "description": "Preset period (default today when no dates are given). Alternatively pass start_date and end_date (max 36 months).",
      "type": "string",
      "enum": [
        "today",
        "yesterday",
        "week",
        "month"
      ]
    },
    "start_date": {
      "description": "Range start, yyyy-mm-dd.",
      "type": "string"
    },
    "end_date": {
      "description": "Range end, yyyy-mm-dd.",
      "type": "string"
    },
    "working_now": {
      "description": "true = only entries that are running right now.",
      "type": "boolean"
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "filter": {
      "type": "string",
      "maxLength": 500,
      "pattern": "^[a-z_]{1,40}=[A-Za-z0-9,_ -]*(;[a-z_]{1,40}=[A-Za-z0-9,_ -]*)*;?$",
      "description": "Filter: key=comma-separated ids, keys separated by ';', e.g. location=36;emp_state=1,2,3. Valid keys and ids come from talenthr_get_directory_filters."
    },
    "sort": {
      "description": "Column to sort by: time, started_at, ended_at, name, tag, location.",
      "type": "string",
      "enum": [
        "time",
        "started_at",
        "ended_at",
        "name",
        "tag",
        "location"
      ]
    },
    "order": {
      "description": "Sort direction.",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: book a time off request for an employee (talenthr_list_time_off_types gives the type id). Unless preapproved=true, TalentHR automatically E-MAILS THE EMPLOYEE'S MANAGER to approve or reject it. preapproved=true auto-approves it when the key's user is allowed to (so no manager decides): only use it when the user explicitly said the time off is already approved. Dates must be within one year from today and inside a time off cycle. Optionally give amount_options (days per date: 1, 0.5, 0 for non-working days; every date from start to end needs a value); when omitted TalentHR works it out. Cannot be undone through this server.

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The employee id (from talenthr_list_employees)."
    },
    "start_date": {
      "type": "string",
      "description": "First day off, yyyy-mm-dd."
    },
    "end_date": {
      "type": "string",
      "description": "Last day off (inclusive), yyyy-mm-dd."
    },
    "timeoff_type_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "Time off type id (from talenthr_list_time_off_types)."
    },
    "preapproved": {
      "description": "true = auto-approve (no manager e-mail decision). Default false.",
      "type": "boolean"
    },
    "amount_options": {
      "description": "Per-day amounts keyed by yyyy-mm-dd, e.g. {\"2026-11-02\":1,\"2026-11-03\":0.5}. Must cover every date from start_date to end_date.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "object",
            "properties": {
              "amount_days": {
                "type": "number"
              },
              "amount_hours": {
                "type": "number",
                "minimum": 0,
                "maximum": 24
              }
            },
            "additionalProperties": false
          }
        ]
      }
    },
    "note": {
      "description": "Note for the approver (max 255 characters).",
      "type": "string",
      "maxLength": 255
    }
  },
  "required": [
    "employee_id",
    "start_date",
    "end_date",
    "timeoff_type_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: approve (accept=true) or reject (accept=false) a pending time off request. TalentHR automatically E-MAILS THE EMPLOYEE the decision. A request that was already answered or canceled cannot be answered again. Only do this when the user explicitly asked for that decision on that request (find ids with talenthr_list_employee_time_off_requests or talenthr_get_calendar).

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The id of the employee who made the request."
    },
    "time_off_request_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The time off request id."
    },
    "accept": {
      "type": "boolean",
      "description": "true = approve, false = reject."
    }
  },
  "required": [
    "employee_id",
    "time_off_request_id",
    "accept"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add an internal note to a job application (visible to the hiring team in TalentHR; no one is e-mailed). Needs the job position id and the application id (talenthr_get_applicant lists an applicant's applications with their job_position_id). Notes cannot be edited or deleted through this server.

{
  "type": "object",
  "properties": {
    "job_position_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The job position id of the application."
    },
    "application_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 2000000000,
      "description": "The application id (from talenthr_get_applicant)."
    },
    "note_text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 30000,
      "description": "The note text (max 30000 characters)."
    }
  },
  "required": [
    "job_position_id",
    "application_id",
    "note_text"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}