Read CharlieHR team members, leave, allowances, offices, teams and salaries; add team member notes. 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": {
"charliehr": {
"url": "https://charliehr.usefulapi.io/mcp"
}
}
}Add to VS Code or add this to .vscode/mcp.json:
{
"servers": {
"charliehr": {
"type": "http",
"url": "https://charliehr.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 CharlieHR client id and CharlieHR client secret.
In Charlie open Company → Integrations → API keys (a Super Admin or Admin) and generate a key pair; the secret is shown only once. The keys act for your whole company. Your keys are used only to call the CharlieHR API on your behalf; they are 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 CharlieHR client id and CharlieHR client secret. 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 CharlieHR connector, then ask in plain words. The AI picks the tools.
| Tool | Type | What it does |
|---|---|---|
charliehr_get_company | read | Get company The Charlie company the API keys belong to: id, name, subdomain and logo. GET /company. |
charliehr_list_offices | read | List offices List the company's offices: id, name, whether it is the head office, address, timezone, phone and email. GET /offices. |
charliehr_get_office | read | Get office One office by id. GET /offices/{id}. |
charliehr_list_teams | read | List teams List the company's teams with the ids of their team members. GET /teams. |
charliehr_get_team | read | Get team One team by id, with the ids of its team members. GET /teams/{id}. |
charliehr_list_team_members | read | List team members List the company's team members (employees): name, work and personal email, phone, address, office, manager, teams, job title, start date, employment status and leaving date. Sensitive fields included: date_of_birth, gender, married, personal email, phone and home address. National Insurance numbers, payroll id, starter declaration and student-loan flags are never returned. GET /team_members. |
charliehr_get_team_member | read | Get team member One team member by id with the full profile (contact details, address, office, manager, teams, dates, employment status, job title, notes). Sensitive fields included: date_of_birth, gender, married, personal email, phone, home address and notes. National Insurance numbers (also inside notes), payroll id, starter declaration and student-loan flags are never returned. GET /team_members/{id}. |
charliehr_get_team_member_working_location | read | Get a team member's working location Where one team member works on a date (custom overrides win over the default assignment). Defaults to today. GET /team_members/{id}/working_location. |
charliehr_get_team_member_working_weeks | read | Get a team member's working weeks The working-week segments of one team member (which days are full_day/morning/afternoon, weekly hours, from/to dates), company defaults and custom overrides. Not paginated. GET /team_members/{id}/working_weeks. |
charliehr_list_working_locations | read | List working locations List the active working locations (the catalog). With a date, instead returns where each active team member works on that date. GET /working_locations. |
charliehr_list_leave_requests | read | List leave requests List leave requests of the whole company (id, team member, approver, status, request type, start/end date, amount and units, duration, details). Optionally only those in a date window. GET /leave_requests. |
charliehr_get_leave_request | read | Get leave request One leave request by id. GET /leave_requests/{id}. |
charliehr_list_team_member_leave_requests | read | List a team member's leave requests The leave requests of one team member, optionally only those in a date window. GET /team_members/{id}/leave_requests. |
charliehr_list_leave_allowances | read | List leave allowances The current holiday allowance of every team member: allowance, used and remaining, in days and hours, with the leave period. GET /leave_allowances. |
charliehr_get_team_member_leave_allowance | read | Get a team member's leave allowance The current holiday allowance of one team member (allowance, used, remaining, in days and hours, with the period). GET /team_members/{id}/leave_allowance. |
charliehr_list_allowance_adjustments | read | List a team member's allowance adjustments All holiday allowance adjustments of one team member across every leave period (description, days/hours, carryover flag, creator, period). GET /team_members/{id}/allowance_adjustments. |
charliehr_list_non_holiday_leave_allowances | read | List a team member's non-holiday leave allowances Days taken and limit for each non-holiday leave type (sick, compassionate...) of one team member. GET /team_members/{id}/non_holiday_leave_allowances. |
charliehr_list_leave_types | read | List leave types The enabled leave types (Holiday, Sick...): id, name, deductible, default, auto-approved, sensitive. GET /leave_types. |
charliehr_get_leave_type | read | Get leave type One leave type by id. GET /leave_types/{id}. |
charliehr_list_company_holidays | read | List company holidays The company's holidays (bank holidays and closures): name, start/end date, duration, deductible. Optionally only those in a date window. GET /company_holidays. |
charliehr_list_restricted_dates | read | List restricted dates The dates on which leave is restricted (e.g. a year-end freeze): name, start/end date, duration. Optionally only those in a date window. GET /restricted_dates. |
charliehr_list_salaries | read | List salaries SENSITIVE: the salary records of all team members (job title, pay rate, pay period, frequency, currency, effective date, employment type). Needs API keys with access to salary data. GET /salaries. |
charliehr_list_team_member_salaries | read | List a team member's salaries SENSITIVE: the salary history of one team member (job title, pay rate, currency, effective date). GET /team_members/{id}/salaries. |
charliehr_list_team_member_note_types | read | List team member note types The custom note types (fields such as Employee No. or Laptop Serial Number) with who may see them. GET /team_member_note_types. |
charliehr_get_team_member_note_type | read | Get team member note type One note type by id. GET /team_member_note_types/{id}. |
charliehr_list_team_member_notes | read | List a team member's notes The custom notes (label and content) stored on one team member (the content of a note labelled as a National Insurance number, and NI-number-looking text, is redacted). GET /team_members/{id}/notes. |
charliehr_create_team_member_note | write | Add a note to a team member WRITE: add a custom note (a value for one note type, e.g. an employee number) to a team member in Charlie. It is created immediately and visible to whoever the note type's permissions allow. Use charliehr_list_team_member_note_types for the note type id. POST /team_members/{id}/notes. |
charliehr_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. | |
charliehr_request_feature | Request a missing feature Tell usefulapi that the user needs something the CharlieHR 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. | |
charliehr_upgrade | Upgrade to Pro (unlimited) Subscribe to the Pro plan for UNLIMITED CharlieHR tool calls (the free tier caps monthly usage). Choose monthly ($9/month) or yearly ($90/year — 2 months free) billing. Returns a short link to open in your browser (it opens Stripe Checkout); after payment your account upgrades automatically. Does not count against the meter. | |
charliehr_cancel_subscription | Cancel the Pro subscription Cancel the caller's CharlieHR 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 charliehr_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 company | $9/mo · $90/yr | Unlimited |
Pro covers this CharlieHR server only. Subscribe with charliehr_upgrade (it returns a Stripe Checkout link). Cancel any time with charliehr_cancel_subscription: Pro continues to the end of the paid period, with no refund for the current period, and running charliehr_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 CharlieHR. The server calls the CharlieHR API with your own CharlieHR 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 CharlieHR client id and CharlieHR client secret. 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 CharlieHR client id and CharlieHR client secret. 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 CharlieHR 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 CharlieHR.
Yes, if you approve it. 1 of the 27 CharlieHR 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, for this CharlieHR server only. Run charliehr_usage_status to see how many calls you used.
Ask the AI to run charliehr_upgrade: it returns a Stripe Checkout link. To cancel, run charliehr_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 charliehr_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.