Read Employment Hero Payroll pay runs, payslips, timesheets and leave; approve or decline leave. 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": {
"keypay": {
"url": "https://keypay.usefulapi.io/mcp"
}
}
}Add to VS Code or add this to .vscode/mcp.json:
{
"servers": {
"keypay": {
"type": "http",
"url": "https://keypay.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.
The login page asks for your Employment Hero Payroll API key and Region.
In Employment Hero Payroll click your name (top right) → My Account → Generate API Key and copy the key. The key acts with your user's permissions; generating a new key invalidates the old one. Choose the region your payroll runs in (Australia, New Zealand, Singapore and Malaysia share one API host; the United Kingdom has its own). Your key is used only to call the Employment Hero Payroll API on your behalf; it is never shown to anyone.
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 Employment Hero Payroll API key and Region. 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 Employment Hero Payroll connector, then ask in plain words. The AI picks the tools.
| Tool | Type | What it does |
|---|---|---|
keypay_get_user | read | Get current user The Employment Hero Payroll user this API key belongs to: id, email, display name and time zone. GET /user. |
keypay_list_businesses | read | List businesses List the payroll businesses this user can access: id, name, region, legal name, contact details, pay cycle, number of employees. Start here: most other tools need a business id. GET /business (OData). |
keypay_get_business | read | Get business One business by id: name, legal name, contact, address, ABN/company details, leave year, standard hours, pay cycle. GET /business/{businessId}. |
keypay_list_employees | read | List employees List the business's employees with basic details: id, name, preferred name, gender, date of birth, contact details, address, start and end date, external id. Tax file, bank and super details are not part of this list. Filter with OData, e.g. "Surname eq 'Smith'". GET /business/{businessId}/employee/details (OData). |
keypay_get_employee | read | Get employee One employee's full record: name, contact, employment type, status, start/end date, pay schedule, primary location and pay category, rate and rate unit, hours per week, award, leave template, work types, tags. Tax file / national insurance / IRD / NRIC numbers, bank accounts and super member numbers are removed. GET /business/{businessId}/employee/unstructured/{employeeId}. |
keypay_get_leave_balances | read | Get employee leave balances An employee's leave balances per leave category (accrued amount and unit), optionally as at a date. GET /business/{businessId}/employee/{employeeId}/leavebalances. |
keypay_list_pay_runs | read | List pay runs List the business's pay runs: id, pay schedule, pay period start/end, date paid, finalised flag, payslips published, notation. Newest first with orderby "PayPeriodEnding desc". GET /business/{businessId}/payrun (OData). |
keypay_get_pay_run | read | Get pay run One pay run by id: pay schedule, period, date paid, whether it is finalised, notation. GET /business/{businessId}/payrun/{payRunId}. |
keypay_list_pay_run_summaries | read | List pay run summaries Pay runs with their totals: total hours, gross wages and net wages, plus the usual pay run fields. GET /business/{businessId}/payrun/summary (OData). |
keypay_get_pay_run_summary | read | Get pay run summary One pay run with its total hours, gross wages and net wages. GET /business/{businessId}/payrun/{payRunId}/summary. |
keypay_get_pay_run_totals | read | Get pay run totals per employee Per-employee totals of a pay run (gross, net, tax withheld, super and the like; the fields depend on the region). Bank payment details are removed. GET /business/{businessId}/payrun/{payRunId}/totals. |
keypay_get_pay_run_payslips | read | Get pay slip data of a pay run Pay slip data for every employee in a pay run, keyed by employee: earnings lines, deductions, tax, super, leave taken and accrued, gross/net and year-to-date totals. Large for big pay runs. Bank account numbers and tax/identity numbers are removed. GET /business/{businessId}/payrun/{payRunId}/payslips. |
keypay_list_pay_run_warnings | read | List pay run warnings Warnings on a pay run (for example an employee paid below their award rate or with a negative net pay): type, employee and message. GET /business/{businessId}/payrun/{payRunId}/warnings. |
keypay_list_timesheets | read | List timesheets List the business's timesheet lines: employee, start/end time, units, work type, location, status, comments, breaks. Filter by employee or date with OData, e.g. "EmployeeId eq 123 and StartTime gt datetime'2026-04-01T00:00:00'". GET /business/{businessId}/timesheet (OData: $filter, $orderby, $top, $skip). |
keypay_get_timesheet | read | Get timesheet line One timesheet line by id. GET /business/{businessId}/timesheet/{timesheetLineId}. |
keypay_list_leave_requests | read | List leave requests List the business's leave requests: employee, leave category, from/to date, total hours, status (Approved, Pending, Rejected, Cancelled), notes. Filter by status, dates, category, location or employee. GET /business/{businessId}/leaverequest. |
keypay_get_leave_request | read | Get leave request One leave request: employee, category, dates, hours, status, notes. GET /business/{businessId}/employee/{employeeId}/leaverequest/{leaveRequestId}. |
keypay_list_leave_categories | read | List leave categories Leave categories of the business (annual, personal/sick, long service...): id, name, unit type, accrual rule. GET /business/{businessId}/leavecategory (OData). |
keypay_list_pay_schedules | read | List pay schedules Pay schedules of the business: id, name, frequency, last date paid, last pay run. Bank and tax account details are removed. GET /business/{businessId}/payschedule (OData). |
keypay_list_locations | read | List locations Locations of the business (sites, departments): id, name, parent, fully qualified name, state. GET /business/{businessId}/location (OData). |
keypay_list_pay_categories | read | List pay categories Pay categories (earnings types) of the business: id, name, rate unit, loadings, super rate, whether leave accrues. GET /business/{businessId}/paycategory (OData). |
keypay_list_work_types | read | List work types Work types of the business: id, name, pay category, leave category, short code. GET /business/{businessId}/worktype (OData). |
keypay_report_gross_to_net | read | Gross to net report Gross-to-net report per employee: earnings by pay category, tax, deductions, super, net pay. Choose a date range (from_date + to_date) or one finalised pay run (pay_run_id). The report has no paging: at most 200 rows are returned (narrow with employee_id or location_id). GET /business/{businessId}/report/grosstonet. |
keypay_report_leave_balances | read | Leave balances report Leave balances of all employees as at a date, per leave category. The report has no paging: at most 200 rows are returned (narrow with location_id or leave_category_id). For one employee use keypay_get_leave_balances. GET /business/{businessId}/report/leavebalances. |
keypay_approve_leave_request | write | Approve leave request WRITE: approves a pending leave request (the employee is notified and the leave is applied to their pay). Check the request first with keypay_get_leave_request. Cannot be undone through this server. POST /business/{businessId}/employee/{employeeId}/leaverequest/{leaveRequestId}/approve. |
keypay_decline_leave_request | write | Decline leave request WRITE: declines a leave request, with an optional reason the employee sees. Check the request first with keypay_get_leave_request. POST /business/{businessId}/employee/{employeeId}/leaverequest/{leaveRequestId}/decline. |
keypay_usage_status | Usage status (free-tier meter) Report the caller's current free-tier usage this month: calls used, monthly limit, remaining, and whether the cap is reached. Read-only; does not count against the meter. | |
keypay_request_feature | Request a missing feature Tell usefulapi that the user needs something the Employment Hero Payroll (KeyPay) 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. | |
keypay_upgrade | Upgrade to Pro (unlimited) Subscribe to the Pro plan for UNLIMITED Employment Hero Payroll (KeyPay) tool calls (the free tier caps monthly usage). Choose monthly ($9/month) or yearly ($90/year — 2 months free) billing. Returns a Stripe Checkout link to open in your browser; after payment your account upgrades automatically. Does not count against the meter. | |
keypay_cancel_subscription | Cancel the Pro subscription Cancel the caller's Employment Hero Payroll (KeyPay) Pro subscription at the end of the paid period (no refund for the current period; unlimited calls continue until then, then the free tier applies). Requires confirm: true. Run keypay_upgrade later to undo the cancel before the period ends. Does not count against the meter. |
| Plan | Price | Limit |
|---|---|---|
| Free | $0 | 50 tool calls / month |
| Proper user | $9/mo · $90/yr | Unlimited |
Pro covers this Employment Hero Payroll server only. Subscribe with keypay_upgrade (it returns a Stripe Checkout link). Cancel any time with keypay_cancel_subscription: Pro continues to the end of the paid period, with no refund for the current period, and running keypay_upgrade before then undoes the cancel. Or write to [email protected].
No. usefulapi is an independent service. It is not affiliated with or endorsed by Employment Hero Payroll. The server calls the Employment Hero Payroll API with your own Employment Hero Payroll 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 Employment Hero Payroll API key and Region. See Before you connect for where to find them.
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 Employment Hero Payroll API key and Region. 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 Employment Hero Payroll 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 Employment Hero Payroll.
Yes, if you approve it. 2 of the 26 Employment Hero Payroll tools can create or change data. The other 24 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, for this Employment Hero Payroll server only. Run keypay_usage_status to see how many calls you used.
Ask the AI to run keypay_upgrade: it returns a Stripe Checkout link. To cancel, run keypay_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 keypay_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.