Read employees, leave, recruiting and reports; book or decide leave and add applicant notes. For HR teams with authorized TalentHR API access. Hosted by usefulapi — connect from Claude, ChatGPT, Cursor, or any MCP client.
Team and Enterprise: an Owner adds the connector for the organization first.
Run this command, then run /mcp in Claude Code to log in:
Add to Cursor or add this to ~/.cursor/mcp.json:
{
"mcpServers": {
"talenthr": {
"url": "https://talenthr.usefulapi.io/mcp"
}
}
}Add to VS Code or add this to .vscode/mcp.json:
{
"servers": {
"talenthr": {
"type": "http",
"url": "https://talenthr.usefulapi.io/mcp"
}
}
}No Add custom MCP server option? It depends on your account or workspace settings: see OpenAI's guide.
Run these commands. The second one opens the login page:
Other MCP clients (Windsurf, Cline, Zed and more): add the URL as a remote MCP server (Streamable HTTP). The client then opens the login page in your browser. Do not add an Authorization header: see Before you connect.
Read the team calendar and an employee’s pending or approved leave requests.
talenthr_get_calendar talenthr_list_employee_time_off_requests
Read an employee’s budget and usage for the current or a selected time-off cycle.
talenthr_get_employee_time_off_budgets
Compare company headcount, hires and leavers for a selected reporting period.
talenthr_get_headcount_report talenthr_get_hires_leaves_report
Create an employee’s time-off request. The manager is emailed for a decision unless preapproval is explicitly chosen and permitted.
Changes data · talenthr_create_time_off_request
Approve or reject a selected pending request when authorized. TalentHR emails the employee the decision.
Changes data · talenthr_reply_time_off_request
Add an internal note to a selected job application for the hiring team.
Changes data · talenthr_create_applicant_note
The login page asks for your TalentHR API key.
Create a key in TalentHR → Settings → Domain settings → API. Choose a read-only key if you only want to look things up: the three write tools then answer with a permission error. HR data is personal data, so give the key to this connection only if you are allowed to. Only connect HR data you are authorized to process with your chosen AI client and its LLM provider: requested employee, candidate, compensation, asset and time-off records reach those services; API keys do not. A customer API-enabled plan is required, and vendor charges are separate. Time-off booking emails the manager (or the employee if the manager is unavailable); approving/rejecting emails the employee. Preapproved requests bypass manager approval when permitted. Recruiting notes are internal. No request is automatically retried; check TalentHR after an uncertain write. Revoke the dedicated API key in TalentHR to stop access. Usage/billing follows the tenant domain when readable, otherwise the key; rotating a key without domain-settings access can change that identity.
Add only the URL. Do not add an Authorization header or an API key to the client config. The server signs you in with OAuth: the login page asks for your TalentHR API key. If the config has such a header, remove it: some clients then send that header instead of the login token, and every call fails with 401.
Turn on the TalentHR connector, then ask in plain words. The AI picks the tools.
| Tool | Type | What it does |
|---|---|---|
talenthr_list_employees | read | List employees (directory) 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. |
talenthr_get_directory_filters | read | Get directory filters 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. |
talenthr_get_employee | read | Get an employee 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. |
talenthr_get_employee_job | read | Get an employee's job history 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. |
talenthr_get_organization_chart | read | Get the organization chart List all current employees with their manager (reports_to_employee_id), job title and role, to answer who reports to whom. |
talenthr_list_departments | read | List departments List all departments of the company with their ids (the ids are what talenthr_list_employees filters and employee records refer to). |
talenthr_list_divisions | read | List divisions List all divisions of the company with their ids (the ids are what talenthr_list_employees filters and employee records refer to). |
talenthr_list_locations | read | List locations 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). |
talenthr_list_job_titles | read | List job titles List all job titles of the company with their ids (the ids are what talenthr_list_employees filters and employee records refer to). |
talenthr_list_time_off_types | read | List time off types 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. |
talenthr_list_employee_time_off_requests | read | List an employee's time off requests 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. |
talenthr_get_employee_time_off_budgets | read | Get an employee's time off balances 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. |
talenthr_get_calendar | read | Get the time off calendar 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. |
talenthr_list_holidays | read | List holidays List the company holidays of a year (current year by default) with date and who they apply to. |
talenthr_list_benefits | read | List benefits 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). |
talenthr_get_employee_benefits | read | Get an employee's benefits List the benefits one employee has (category, cost, start and end date). |
talenthr_list_assets | read | List company assets 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). |
talenthr_get_employee_assets | read | Get an employee's assets List the assets (inventory and memberships) assigned to one employee. Paged: use next_offset to continue. |
talenthr_list_job_positions | read | List job positions 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. |
talenthr_list_job_position_applicants | read | List applicants of a job position 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. |
talenthr_list_applicants | read | List all applicants 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). |
talenthr_get_applicant | read | Get an applicant 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. |
talenthr_get_headcount_report | read | Get the headcount report Headcount per month over a period (total and optionally grouped by gender, location, department, division, ...), plus the current headcount. |
talenthr_get_hires_leaves_report | read | Get the hires and leaves report Hires, terminations and attrition rate per month over a period. |
talenthr_get_time_off_report | read | Get the time off report Approved, non-canceled time off summarized per month and per weekday, split by time off type, for a period. |
talenthr_list_time_tracking_entries | read | List time tracking entries 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. |
talenthr_create_time_off_request | write | Book a time off request 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. |
talenthr_reply_time_off_request | write | Approve or reject a time off request 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). |
talenthr_create_applicant_note | write | Add a note to a job application 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. |
talenthr_usage_status | Usage status (free-tier meter) Report the caller's current usage: the plan, calls used this month, the limit of the plan (the free monthly cap or the Pro fair use limit), remaining, and whether the limit is reached. Read-only; does not count against the meter. | |
talenthr_request_feature | Request a missing feature Tell usefulapi that the user needs something the TalentHR tools cannot do yet (a missing tool, field or filter). Call it only when the user asks for something none of the tools can do, and tell the user that you send the request. Do not call it for errors or for normal requests. Do not include personal data, credentials or customer records. Stored with the product name and the client type (for example Claude or Cursor), without the user's account. At most 5 requests per day. Does not count against the meter. | |
talenthr_upgrade | Upgrade to Pro (unlimited*) Get Pro: unlimited tool calls (fair use limit: 10,000 a month) on TalentHR (the free tier caps monthly usage). Plans: "monthly" — $9/month; "yearly" — $90/year (2 months free). Cancel any time: Pro then runs to the end of the paid period, so it also suits a one-time job. *A fair use limit applies. For heavy use (near Pro's limit): "plus" or "plus_yearly" — Pro+, $39/month or $390/year, unlimited tool calls (fair use limit: 100,000 a month); an existing Pro subscription changes to Pro+ in place (needs confirm: true; the price difference for the rest of the period is charged at once). Otherwise returns a short link to open in your browser (it opens Stripe Checkout); after payment the account upgrades automatically. Does not count against the meter. | |
talenthr_cancel_subscription | Cancel the Pro subscription Cancel the caller's TalentHR Pro subscription at the end of the paid period (no refund for the current period; Pro continues until then, then the free tier applies). Requires confirm: true. Run talenthr_upgrade later to undo the cancel before the period ends. Does not count against the meter. |
| Plan | Price | Limit |
|---|---|---|
| Freeper TalentHR tenant/key | $0 | 50 tool calls / month |
| Proper TalentHR tenant/key | $9/mo · $90/yr | Unlimited* |
*Pro fair use limit: 10,000 tool calls a month on this server. For more, write to [email protected].
Pro covers this TalentHR server only. Subscribe with talenthr_upgrade (it returns a Stripe Checkout link). Cancel any time with talenthr_cancel_subscription: Pro continues to the end of the paid period, with no refund for the current period, and running talenthr_upgrade before then undoes the cancel. Or write to [email protected].
Review team availability. Check leave balances. Review headcount trends. Book agreed time off. Respond to pending leave. Record a recruiting note. See what you can do for the details.
No. usefulapi is an independent service. It is not affiliated with or endorsed by TalentHR. The server calls the TalentHR API with your own TalentHR access, so it sees only the data that your account can see.
Yes. In Claude, add this server's URL as a custom connector. In ChatGPT, add it as a custom MCP server in Plugins. Then log in once. Cursor, VS Code, Claude Code and Codex work too. See the setup steps.
The login page asks for your TalentHR API key. See Before you connect for where to find it.
No. Add only the URL. Do not add an Authorization header or an API key to the client config. The server signs you in with OAuth: the login page asks for your TalentHR API key. If the config has such a header, remove it: some clients then send that header instead of the login token, and every call fails with 401.
The login stores them encrypted in the authorization grant of your connection. The server uses them to call the TalentHR API for you and to derive a private account id for usage metering. usefulapi does not show them on any page or in any reply. To stop all access, remove the connector and change or delete these credentials in TalentHR.
Yes, if you approve it. 3 of the 29 TalentHR tools can create or change data. The other 26 are marked read-only. Most MCP clients ask you to approve a tool call before it runs.
The Free plan gives 50 tool calls / month. Pro costs $9/mo or $90/yr, with unlimited tool calls (fair use limit: 10,000 tool calls a month), for this TalentHR server only. Cancel any time: Pro then runs to the end of the paid period. Run talenthr_usage_status to see how many calls you used.
Ask the AI to run talenthr_upgrade: it returns a Stripe Checkout link. To cancel, run talenthr_cancel_subscription. Pro continues to the end of the paid period.
Tell the AI what you wanted to do. It can send the request with talenthr_request_feature. We store the text with the server name, the type of AI client and the tool you tried, not with your account, and read every request when we plan new tools. You can send up to 5 requests per day.
Any client that supports remote MCP servers (Streamable HTTP) with OAuth login: Claude (web and desktop), Claude Code, ChatGPT, Codex, Cursor, VS Code, Windsurf and others.
This is a Model Context Protocol endpoint — meant to be connected from an AI client, not opened in a browser. An invalid_token response at the URL is the auth gate working as designed; clients authenticate automatically.
Need a tool this server does not have, or a connection to another system? We build custom integrations and MCP servers.