Mcp

Tools Reference

Complete reference for all BookYourPTO MCP tools — parameters, descriptions, required roles, and usage examples.

BookYourPTO MCP exposes 32 tools organized into 9 categories. Each tool is described below with its parameters and required permissions.

Authentication

Authentication is handled automatically via OAuth 2.0. When you first connect, your browser will open a BookYourPTO login page. After you sign in, your AI client receives a secure token — no credentials are ever shared with the AI.

There is no login tool. Authentication happens in your browser before the AI session starts. Two-factor authentication (2FA) is fully supported.

Leaves

`create_leave_request`

Submit a new leave request. Use get_leave_balance first to check availability.

Parameter	Type	Required	Description
`userId`	string	Yes	User ID for whom to create the leave
`leaveTypeId`	string	Yes	Leave type ID (use `bypto://leave-types` resource to look up)
`startDate`	string	Yes	Start date (`YYYY-MM-DD`)
`endDate`	string	Yes	End date (`YYYY-MM-DD`)
`startHalf`	enum	No	First day duration: `FULL_DAY`, `FIRST_HALF`, or `SECOND_HALF`. Default: `FULL_DAY`
`endHalf`	enum	No	Last day duration: `FULL_DAY`, `FIRST_HALF`, or `SECOND_HALF`. Default: `FULL_DAY`
`reason`	string	No	Reason for leave

`query_leaves`

List leave requests. Filters by user, year, and status. Employees see their own; managers/admins see others.

Parameter	Type	Required	Description
`userId`	string	No	User ID to query (defaults to authenticated user)
`year`	number	No	Year to query (defaults to current year)
`status`	string	No	Filter by status: `PENDING`, `APPROVED`, `REJECTED`, `CANCELLED`

`get_leave_balance`

Get leave balance breakdown (annual, sick, carried over) for a user and year.

Parameter	Type	Required	Description
`userId`	string	No	User ID (defaults to authenticated user)
`year`	number	No	Fiscal year (defaults to current year)

`get_pending_leave_approvals`

List pending leave requests awaiting approval.

Required role: DEPARTMENT_HEAD, ADMINISTRATOR, or EXECUTIVE

No parameters.

`approve_or_reject_leave`

Approve or reject a pending leave request.

Required role: DEPARTMENT_HEAD, ADMINISTRATOR, or EXECUTIVE

Parameter	Type	Required	Description
`leaveId`	string	Yes	ID of the leave request
`action`	enum	Yes	`approve` or `reject`
`reason`	string	No	Rejection reason (required if rejecting)

Time Tracking

`get_time_tracking_status`

Get current clock status (clocked in / out / on break) and today's summary for a user.

Parameter	Type	Required	Description
`userId`	string	No	User ID (defaults to authenticated user)

`clock_action`

Clock in, clock out, start break, or end break.

Parameter	Type	Required	Description
`action`	enum	Yes	`clock_in`, `clock_out`, `start_break`, or `end_break`
`projectId`	string	No	Project ID (for `clock_in`, if required by org settings)
`taskId`	string	No	Task ID (for `clock_in`)
`description`	string	No	Work description (for `clock_in`)

`query_time_entries`

List time entries filtered by user, date range, and project. Supports pagination.

Parameter	Type	Required	Description
`userId`	string	No	User ID (defaults to authenticated user for employees)
`startDate`	string	No	Start date filter (`YYYY-MM-DD`)
`endDate`	string	No	End date filter (`YYYY-MM-DD`)
`projectId`	string	No	Filter by project ID
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page, max 50 (default: 20)

Expenses

`query_expenses`

List expense reports. Filters by user, status, and date range. Employees see own; managers/admins see others.

Parameter	Type	Required	Description
`userId`	string	No	User ID to filter by
`status`	string	No	Filter by status: `DRAFT`, `SUBMITTED`, `PENDING_APPROVAL`, `APPROVED`, `REJECTED`, `PAID`, `CANCELLED`
`startDate`	string	No	Start date (`YYYY-MM-DD`)
`endDate`	string	No	End date (`YYYY-MM-DD`)
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 20)

`get_expense_details`

Get full details of an expense report including line items, per diems, and mileage entries.

Parameter	Type	Required	Description
`expenseId`	string	Yes	Expense report ID

`get_expense_approvals`

List expense reports pending your approval.

Required role: Manager, DEPARTMENT_HEAD, ADMINISTRATOR, or EXECUTIVE

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 20)

`approve_or_reject_expense`

Approve or reject a submitted/pending expense report.

Required role: Manager, DEPARTMENT_HEAD, ADMINISTRATOR, or EXECUTIVE

Parameter	Type	Required	Description
`expenseId`	string	Yes	Expense report ID
`action`	enum	Yes	`approve` or `reject`
`notes`	string	No	Approver notes or rejection reason

`create_expense`

Create a new expense report.

Required role: All roles (company card report type may require ADMINISTRATOR or EXECUTIVE depending on organization settings)

Parameter	Type	Required	Description
`title`	string	Yes	Expense report title
`departureDate`	string	Yes	Departure date (`YYYY-MM-DD`)
`returnDate`	string	Yes	Return date (`YYYY-MM-DD`)
`reportType`	enum	No	`REIMBURSEMENT` or `COMPANY_CARD` (default: `REIMBURSEMENT`)
`description`	string	No	Report description
`tripPurpose`	string	No	Purpose of trip or expense
`currency`	string	No	Currency code (defaults to organization currency)
`departmentId`	string	No	Department ID
`projectId`	string	No	Project ID
`payableToId`	string	No	User ID the expense is payable to

`submit_expense`

Submit a draft expense report for approval.

Required role: Report owner, ADMINISTRATOR, or EXECUTIVE

Parameter	Type	Required	Description
`expenseId`	string	Yes	Expense report ID

`mark_expense_paid`

Mark an approved expense report as paid. Triggers QuickBooks sync if configured.

Required role: ADMINISTRATOR or EXECUTIVE

Parameter	Type	Required	Description
`expenseId`	string	Yes	Expense report ID
`paymentReference`	string	No	Payment reference number
`paymentMethod`	enum	No	`DIRECT_DEPOSIT`, `CHEQUE`, `WIRE_TRANSFER`, `CASH`, `CREDIT_CARD`, or `OTHER`

`get_expense_settings`

Get organization expense settings including approval rules, receipt requirements, company card configuration, and mileage rates.

No parameters.

Users

`get_team_members`

List all users in the organization with their role, department, and manager info.

No parameters.

`get_user_profile`

Get detailed profile for a specific user by ID.

Parameter	Type	Required	Description
`userId`	string	Yes	User ID

`get_departments`

List all departments in the organization.

No parameters.

Organization

`get_org_info`

Get organization settings: name, timezone, currency, leave allowances, fiscal year, etc.

No parameters.

`get_public_holidays`

List public holidays configured for the organization.

Parameter	Type	Required	Description
`year`	number	No	Filter by year

`get_dashboard_stats`

Get organization-level stats: total users, departments, leave types, leaves.

Required role: EXECUTIVE

No parameters.

`get_notifications`

Get the authenticated user's notifications. Supports filtering by read status.

Parameter	Type	Required	Description
`filter`	enum	No	`all`, `unread`, or `read` (default: `all`)
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 20)

Projects

`list_projects`

List projects visible to the authenticated user. Admins see all; others see their department + org-wide projects.

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `ACTIVE`, `COMPLETED`, `ARCHIVED`, `ON_HOLD`
`includeStats`	boolean	No	Include time tracking stats (default: false)

`get_project`

Get full project details including tasks, client info, and time stats.

Parameter	Type	Required	Description
`projectId`	string	Yes	Project ID

`create_task`

Create a new task within a project.

Parameter	Type	Required	Description
`projectId`	string	Yes	Project ID
`name`	string	Yes	Task name
`description`	string	No	Task description
`budgetHours`	number	No	Budget hours for this task
`isBillable`	boolean	No	Whether the task is billable (default: true)

Schedules

`query_schedules`

List scheduled shifts for a date range. Returns shifts, leaves, and public holidays. Admins see all; department heads see their department.

Parameter	Type	Required	Description
`startDate`	string	No	Start date (`YYYY-MM-DD`, defaults to today)
`endDate`	string	No	End date (`YYYY-MM-DD`, defaults to +7 days)
`userId`	string	No	Filter by user ID
`departmentId`	string	No	Filter by department ID

`create_shift`

Create a new scheduled shift. Omit userId to create an open shift.

Required role: ADMINISTRATOR, EXECUTIVE, or DEPARTMENT_HEAD

Parameter	Type	Required	Description
`date`	string	Yes	Shift date (`YYYY-MM-DD`)
`startTime`	string	Yes	Start time (`HH:MM`, e.g., `09:00`)
`endTime`	string	Yes	End time (`HH:MM`, e.g., `17:00`)
`userId`	string	No	User ID (omit for open shift)
`departmentId`	string	No	Department ID
`shiftType`	string	No	`REGULAR`, `MORNING`, `AFTERNOON`, `NIGHT`, `CUSTOM` (default: `REGULAR`)
`breakDuration`	number	No	Break duration in minutes (default: 30)
`notes`	string	No	Notes

`publish_schedule`

Publish schedules for a week, making them visible to employees.

Required role: ADMINISTRATOR or EXECUTIVE

Parameter	Type	Required	Description
`weekStart`	string	Yes	Monday of the week to publish (`YYYY-MM-DD`)
`numberOfWeeks`	number	No	Number of weeks to publish, 1-4 (default: 1)
`sendNotification`	boolean	No	Send email notification to employees (default: true)

Reports

`generate_leave_report`

Generate a leave report for a date range.

Required role: ADMINISTRATOR or EXECUTIVE

Parameter	Type	Required	Description
`startDate`	string	No	Report start date (`YYYY-MM-DD`)
`endDate`	string	No	Report end date (`YYYY-MM-DD`)
`departmentId`	string	No	Filter by department
`userId`	string	No	Filter by user

`generate_timesheet_report`

Generate a timesheet report for a date range.

Required role: ADMINISTRATOR or EXECUTIVE

Parameter	Type	Required	Description
`startDate`	string	No	Report start date (`YYYY-MM-DD`)
`endDate`	string	No	Report end date (`YYYY-MM-DD`)
`userId`	string	No	Filter by user
`projectId`	string	No	Filter by project

Connecting

Step-by-step instructions for connecting your AI tool to BookYourPTO using MCP. Supports Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, and ChatGPT.

Security

Authentication, role-based access control, and security best practices for BookYourPTO MCP.