Model Context Protocol
MCP server for time off and attendance
Let AI run the hours. Keep the ledger here.
ChatGPT, Claude, Cursor, Codex, and Grok connect to TimeOff Manager MCP and answer who is on leave, who is clocked in, and what hours you can pay — then approve leave when you say so. You give the AI one company key. TimeOff Manager keeps the punches, the balances, and the audit trail. Staff still clock in on the phone and the kiosk.
What is TimeOff Manager MCP?
MCP — Model Context Protocol — is how ChatGPT, Claude, Cursor, Codex, and Grok call TimeOff Manager. You paste one company API key. The assistant can then answer who is on leave, who is clocked in, and the hours you can pay, and approve leave when you say so.
The remote MCP server is POST https://timeoffmanager.us/api/mcp. The same key works over REST. Staff still use TimeOff Manager Pro and the kiosk. Leave and attendance stay in one ledger with PTO software and time tracking software.
What you say to ChatGPT or Claude
After the key is connected, paste one of these into the chat. The AI calls TimeOff Manager. You do not look up the endpoint.
- Who is on leave today, and how many people are clocked in?
- What is waiting on me — leave, missed punches, mileage, and time changes?
- How many hours did each person work from September 14 to September 27, with overtime called out?
- Approve Maya’s vacation if nobody else on her team is off those days. Otherwise leave it and say why.
Connect ChatGPT, Claude, Cursor, Codex, or Grok
Do the key once. Then open the app you already use and fill in the fields below. The AI only sees that one company. It cannot create the company, take a card, or replace the kiosk.
-
1. Open API keys
Sign in to the company. Go to API keys. Create a key and name it for the AI, for example “ChatGPT payroll.”
-
2. Copy the key
It starts with tk_. Leave scopes empty for full access to that company, or turn off write scopes if this AI should only look.
-
3. Paste it below
Every app uses https://timeoffmanager.us/api/mcp. Replace tk_REPLACE_ME with the key you just copied.
Cursor
- Open Customize in the sidebar, then MCP, and add a custom server. That opens mcp.json.
- For every project, the file is ~/.cursor/mcp.json. For one project, it is .cursor/mcp.json in that folder. Do not commit a real key.
- Paste this, replace the key, and save. Ask in chat: who is on leave today?
{
"mcpServers": {
"timeoff-manager": {
"url": "https://timeoffmanager.us/api/mcp",
"headers": { "Authorization": "Bearer tk_REPLACE_ME" }
}
}
}Claude
- In Claude, open Customize, then Connectors, then Add custom connector. On a Team or Enterprise plan, an Owner adds it under Organization settings, then Connectors, then Add, then Custom. If it asks for a type, choose Web.
- Name: TimeOff Manager. Server URL: https://timeoffmanager.us/api/mcp
- Choose no sign-in. Under Request headers, set the name to authorization and the value to Bearer tk_REPLACE_ME — the word Bearer, a space, then the key. Leave the OAuth client id and secret empty. That is not where the key goes.
- Add it. In a chat, open the + menu, turn TimeOff Manager on, and ask who is clocked in.
If you do not see Request headers, add it in Claude Code instead:
claude mcp add --transport http timeoff-manager https://timeoffmanager.us/api/mcp \
--header "Authorization: Bearer tk_REPLACE_ME"ChatGPT
- Open your profile, then Settings, then Apps. The label is sometimes Apps & Connectors. Turn on Developer mode under Advanced. If the toggle is missing, a workspace admin has to allow custom connectors first.
- Choose Create. Name: TimeOff Manager. Description: Time off, attendance, and payroll hours for one company.
- Server URL: https://timeoffmanager.us/api/mcp
- Authentication: Token. Paste only the key, starting with tk_. Do not type the word Bearer in that box. ChatGPT adds it.
- Scan tools, then Create. In a new chat, turn the app on and ask what leave is waiting on you.
Codex
- Open ~/.codex/config.toml on your computer.
- Paste this block at the end. Replace the key. Save.
- Start a new Codex session and ask for this pay period’s hours, with overtime called out.
[mcp_servers.timeoff_manager]
url = "https://timeoffmanager.us/api/mcp"
http_headers = { Authorization = "Bearer tk_REPLACE_ME" }Grok
- This block goes in the tools list of a Grok API request, or in a Grok client that accepts a remote MCP URL.
- Paste it and replace the key. authorization includes the word Bearer and a space.
- A grok.com chat does not always have a box for this URL. If you do not see one, use the API.
{
"type": "mcp",
"server_url": "https://timeoffmanager.us/api/mcp",
"server_label": "timeoff_manager",
"authorization": "Bearer tk_REPLACE_ME"
}The AI can also reach any other company path through call_openapi, using the OpenAPI file. The key’s scopes still apply. A read-only key cannot approve leave or invite people. Keep the real key out of a public GPT and out of git.
The same jobs over the TimeOff Manager API
Create the key in TimeOff Manager under API keys. Send it as X-API-Key or Authorization: Bearer. Base URL https://timeoffmanager.us. Replace tk_REPLACE_ME with your key, and keep the real key out of a public repo.
Who is on leave today, and how many people are clocked in
clocked_in is a count of open punches. on_leave names each person. Named live pins, when that feature is on, are GET /api/v1/live-location/map.
curl https://timeoffmanager.us/api/v1/reports/coverage \
-H "X-API-Key: tk_REPLACE_ME"{
"data": {
"date": "2026-09-30",
"clocked_in": 7,
"on_leave": [
{ "employee_id": 42, "name": "Maya Chen", "type": "vacation", "status": "approved" }
]
}
}Hours you can pay
Same paid-hours set as the Excel payroll report for that date range. from and to are required. The sample below keeps the pay fields. The live payload also includes daily hours, holidays, and mileage.
curl "https://timeoffmanager.us/api/v1/reports/payroll-hours?from=2026-09-14&to=2026-09-27" \
-H "X-API-Key: tk_REPLACE_ME"{
"data": {
"start_date": "2026-09-14",
"end_date": "2026-09-27",
"employees": [
{ "employee_name": "Maya Chen", "regular_hours": 76.5, "overtime_hours": 2.0 }
],
"totals": { "regular_hours": 640.0, "overtime_hours": 18.5 }
}
}Approve a pending leave request
Needs leave:write. This fires leave_request.approved. Pending items of every kind are GET /api/v1/approvals.
curl -X POST https://timeoffmanager.us/api/v1/leave-requests/18/approve \
-H "X-API-Key: tk_REPLACE_ME"The API reference lists employees, invites, schedules, missed punches, mileage, blackout dates, and the rest. Each key belongs to one company. Creating the company and the key stays in the admin.
Your app reacts when leave is approved
Register a URL. TimeOff Manager POSTs this body and signs the raw JSON with HMAC-SHA256 in X-TimeOff-Signature. The event name is also in X-TimeOff-Event.
curl -X POST https://timeoffmanager.us/api/v1/webhooks \
-H "X-API-Key: tk_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks/timeoff","events":["leave_request.approved"]}'{
"event": "leave_request.approved",
"triggered_at": "2026-09-30T16:04:00-04:00",
"data": {
"id": 18,
"employee_id": 42,
"status": "approved"
}
}Other events: leave_request.created, leave_request.rejected, time_entry.completed, time_entry.approved, forgot_punch.approved, mileage_trip.approved, payroll_day_adjustment.approved, payroll_run.approved.
You keep the product. This keeps the ledger.
- Whose “today” it is when the company and the worker are in different time zones
- Overnight shifts, missed punches, and an audit trail a manager can defend
- GPS, geofence, and a live answer to who is on site
- Vacation, sick, and personal balances, accruals, blackout dates, and US and Canadian holidays
- Overtime rules, pay-period hours, mileage, and approvals
You build
The workflow, the industry UI, the agent
TimeOff Manager keeps
Employees, punches, schedules, leave balances, approvals
You build
What happens when a webhook fires
TimeOff Manager keeps
The event and the underlying record
You build
A key with only the scopes you need
TimeOff Manager keeps
Isolation to that one company
Security and field teams
Your dispatch board calls coverage and the live map, then invoices the client from payroll hours.
Staffing and home care
Your placement tool writes the schedule and reads the hours. Coverage and time off stay in one ledger.
An HRIS that already has people
Push employees and invites in. Leave the clock, the kiosk, and the balance math here.
A payroll bureau
A read-only key pulls this period’s hours, overtime, and mileage into the sheet you already send.
Those questions hit get_coverage, list_approvals, get_payroll_hours, and approve_leave_request. You can name the tool, or just ask in plain language.
TimeOff Manager MCP questions
- What is TimeOff Manager MCP?
- TimeOff Manager MCP is a remote Model Context Protocol server at https://timeoffmanager.us/api/mcp. ChatGPT, Claude, Cursor, Codex, and Grok use one company API key to read who is on leave, who is clocked in, and the hours you can pay — then approve leave when you say so. TimeOff Manager keeps the punches, balances, and audit trail.
- What is the TimeOff Manager MCP server URL?
- POST https://timeoffmanager.us/api/mcp. Every host on this page uses that URL. ChatGPT’s token field gets the key alone. Claude, Cursor, Codex, and the Grok API send Authorization: Bearer plus the key.
- How do I connect ChatGPT to TimeOff Manager?
- Create a company API key under API keys. In ChatGPT, open Settings, then Apps, turn on Developer mode, and create a custom connector. Server URL https://timeoffmanager.us/api/mcp. Authentication is Token — paste only the tk_ key. Scan tools, create, turn the app on in a new chat, and ask who is clocked in.
- Can Claude, Cursor, Codex, or Grok use the same MCP server?
- Yes. The same server URL and the same company key work in Claude (Connectors), Cursor (mcp.json), Codex (config.toml), and the Grok API. A read-only key cannot approve leave or invite people.
- Can one MCP key see every company?
- No. Each key belongs to one company. The company is created in TimeOff Manager. Staff still clock in with TimeOff Manager Pro and the kiosk. The key does not replace those apps.
- Is the REST API the same as MCP?
- MCP wraps the company REST API. Named tools cover coverage, approvals, hours, and leave. call_openapi reaches any other company path in the OpenAPI file. The HTML reference is at /api-docs. Download OpenAPI 3.1 from /api/openapi.yaml or /api/openapi.json.
- Can the AI approve leave?
- Yes, if the key has leave:write. A read-only key can pull hours and coverage and cannot approve leave or invite people. Creating the company, card checkout, and API keys stay in the admin. Face verification and PIN clock-in stay on the kiosk and phone.
- How is this like Stripe?
- You build the product. TimeOff Manager keeps the ledger: employees, punches, leave balances, schedules, approvals, and hours you can send to payroll software. A company API key is the secret for that one company, the way a Stripe secret key is the secret for one account. Webhooks tell your app when leave is approved, a shift ends, or mileage is approved.
One ledger for hours and leave. Your product on top.
Start a company, create a key, and connect an AI — or call the API from the product you are building. Staff keep using TimeOff Manager Pro and the kiosk.