Overview

Connect AI assistants to your BookYourPTO workspace using the Model Context Protocol (MCP). Manage leaves, time tracking, expenses, schedules, HR, performance, and more from any MCP-compatible client.

What is BookYourPTO MCP?

BookYourPTO MCP is a hosted server that gives AI tools secure access to your BookYourPTO workspace. Built on the Model Context Protocol (MCP) open standard, it lets AI assistants — Claude.ai connectors, Claude Code, Claude Desktop, Cursor, VS Code Copilot, and more — interact with your HR data through natural language.

Looking for the assistant inside the app? That is BookYourPTO Intelligence, which needs no set-up. This section is about connecting your own AI client to BookYourPTO.

How It Works

┌─────────────────┐  Streamable HTTP  ┌──────────────────┐      REST API     ┌──────────────────┐
│   AI Client     │ ◄──────────────►  │  BookYourPTO MCP │ ◄───────────────► │  BookYourPTO API │
│ (Claude.ai,     │   POST /mcp       │  Server (hosted) │   Authenticated   │  (app.bookyourpto│
│  Cursor, Code…) │   Tool calls      │  mcp.bookyourpto │   API requests    │  .com)           │
└─────────────────┘                   │  .com            │                   └──────────────────┘
                                      └──────────────────┘
  1. Your AI client connects to https://mcp.bookyourpto.com/mcp using Streamable HTTP (MCP spec 2025-11-25)
  2. The MCP server prompts you to sign in via your browser (OAuth 2.0 with PKCE) — your password never touches the AI
  3. When the AI needs to take an action (e.g., check leave balance), it calls the appropriate MCP tool
  4. The MCP server makes authenticated API requests to BookYourPTO on your behalf
  5. Results are returned to the AI client, which formats them into a natural response
Transport. BookYourPTO MCP uses Streamable HTTP (POST /mcp), the current MCP transport (spec 2025-11-25). The older SSE endpoint (/sse) remains available for one release for backward compatibility, but new integrations should use /mcp.

What Can You Do?

With BookYourPTO MCP, your AI assistant can:

  • Manage leaves — Check balances, submit requests, approve/reject, request and decide cancellations, group-book team leave
  • Track time — Clock in/out, manage breaks, query and edit time entries, submit and finalize timesheets
  • Handle expenses — Create, submit, approve/reject, mark paid, scan and upload receipts, manage per diems and mileage
  • Run schedules — View, create, and publish shifts
  • Manage projects — Projects, tasks, issues, comments, and the project board
  • HR records — Compensation, bonuses, job history, custom profile fields, certifications, visas, assets, onboarding/offboarding
  • Performance — Review cycles, assessments, goals, and 1:1s
  • Training & benefits — Courses, assignments, plans, and enrollments
  • Documents — E-signature send, templates and template versions, signer reminders, bulk send, audit trail
  • Admin — Org settings, security/audit logs, billing, QuickBooks, Slack/Teams integrations, password/2FA, GDPR
  • Reports & org info — Leave/timesheet reports, team directory, departments, holidays, dashboard stats

Available Tools

BookYourPTO MCP provides 385 tools across 18 categories:

CategoryToolsDescription
Admin94Org settings, security/audit logs, billing, QuickBooks, Slack/Teams and email test sends, white-label domains, password/2FA, GDPR
HR73Compensation, bonuses, job and status history, employee records, custom profile fields, certifications, visas, assets, onboarding
Performance37Review cycles, assessments, templates, goals + comments, 1:1 series and meetings
Expenses25Reports, approvals, mark-paid, settings, receipt scan and upload, per diems, mileage
Users21Profiles, directory search, departments, teams, org chart, roles, offboarding
Documents21E-signature, templates with versions and archive/restore, signer reminders, bulk send, audit trail
Organization17Org info, holidays and per-person holiday overrides, categories, dashboard, notifications, directory settings
Time Tracking15Clock in/out, breaks, time entries, approvals, timesheet submission and sign-off
Projects15Projects, tasks, issues, comments, board
Training14Courses, categories, assignments, enrollments
Leaves12Balances, requests, approvals, cancellation requests, group booking
Schedules12Query, create, and publish shifts
Calendar8Google/Outlook connect, iCal feeds
Benefits8Plans and enrollments
Clients5CRM client records
Notifications5System notifications, unread counts
Reports2Leave and timesheet reports
System1Health check

A self-hosted server running in per-user mode also registers a login tool; OAuth connections, including the hosted server, do not see it.

See the Tools Reference for complete documentation of every tool and its parameters.

Resources

The MCP server exposes read-only resources that give AI clients cached context without a tool call (12 total):

URIDescription
bypto://org/settingsOrganization configuration (timezone, currency, fiscal year)
bypto://leave-typesAvailable leave types and their settings
bypto://team/directoryTeam members with roles and departments
bypto://current-userThe authenticated user's profile
bypto://departmentsDepartments list
bypto://projectsProjects list
bypto://expense-categoriesExpense categories from org settings
bypto://document-templatesDocument templates
bypto://onboarding-templatesOnboarding templates
bypto://benefit-plansBenefit plans
bypto://training-coursesTraining courses
bypto://training-categoriesTraining categories

Prompts (slash commands)

The server also ships 10 prebuilt prompts — multi-step workflows your client surfaces as slash commands:

onboard-employee · offboard-employee · expiring-credentials · plan-team-capacity · expense-month-end-close · quarterly-performance-review · training-compliance-check · send-handbook-to-new-hires · audit-report · security-incident-response

Requirements

  • A BookYourPTO Cloud account (Pro, Business, or Enterprise plan)
  • An MCP-compatible AI client (see Connecting)
  • Your BookYourPTO credentials (you'll sign in via your browser when first connecting)

The fastest way to connect Claude Code, Cursor, VS Code or Windsurf is the Setup Wizard: npx -y @bookyourpto/wizard@latest mcp add.