Security
Authentication
BookYourPTO MCP uses OAuth 2.0 with PKCE for authentication. You sign in via your browser on BookYourPTO's domain — your password never touches the AI client or the MCP server.
How it works
- Your AI client connects to the MCP server over Streamable HTTP (
POST /mcp) - Unauthenticated requests get a
401pointing at the server's OAuth metadata; your client discovers the endpoints and opens a browser window - You sign in on BookYourPTO's login page (supports email/password and two-factor authentication)
- BookYourPTO issues an authorization code, which is exchanged — with PKCE (S256) — for a short-lived JWT access token
- Tokens are refreshed automatically for the duration of your session
- All tool calls run with your identity and permissions
AI Client MCP Server BookYourPTO
│ │ │
│── POST /mcp ──────────►│ │
│◄── 401 (OAuth meta) ───│ │
│ │ │
│── Browser opens ──────►│── redirect ───────────►│
│ │ │── User logs in
│◄── code + state ───────│◄── redirect ───────────│ (browser)
│ │ │
│── POST /token (PKCE) ─►│── proxy ──────────────►│
│◄── access_token ───────│◄── tokens ─────────────│
│ │ │
│── POST /mcp + Bearer ─►│ │
│◄══ tool results ═══════│ │
Standards & guards
- PKCE is S256-only — plaintext code challenges are rejected.
- OAuth metadata is published at the standard discovery endpoints:
GET /.well-known/oauth-authorization-server(RFC 8414)GET /.well-known/oauth-protected-resource(RFC 9728)
/mcpis protected by an Origin allow-list (DNS-rebinding protection). A browser request from an origin that is not on the list is refused.- The protocol version is negotiated during the MCP
initializehandshake. The server can also run in a strict mode that refuses any later request without a matchingMCP-Protocol-Versionheader. - Tokens are JWTs verified locally against the BookYourPTO instance's signing secret — no extra network round-trip per call.
Requirements
- A BookYourPTO account (any role)
- Two-factor authentication (2FA) is fully supported — if enabled, you'll enter your TOTP code on the login page
Role-Based Access Control
The MCP server inherits the permissions of the authenticated user. Tools enforce the same role-based access rules as the BookYourPTO web application — across all 385 tools, not just the examples below.
Role hierarchy
| Role | Level | Description |
|---|---|---|
EMPLOYEE | Basic | View own data only |
DEPARTMENT_HEAD | Manager | View/manage own department |
ADMINISTRATOR | Admin | Full access to all features |
EXECUTIVE | Executive | Full access + org-wide analytics |
Tool permissions by role (representative sample)
The table below illustrates the model with common tools. The same enforcement applies to every tool — administrative surfaces (billing, security/audit logs, QuickBooks, GDPR, white-label domains) require ADMINISTRATOR or EXECUTIVE, while self-service tools are available to all roles for their own data. See the Tools Reference for each tool's risk level and behaviour.
| Tool | EMPLOYEE | DEPT_HEAD | ADMIN | EXECUTIVE |
|---|---|---|---|---|
query_leaves (own) | Yes | Yes | Yes | Yes |
query_leaves (others) | Per org visibility settings | Per org visibility settings | All | All |
create_leave_request | Yes | Yes | Yes | Yes |
get_leave_balance (own) | Yes | Yes | Yes | Yes |
get_leave_balance (others) | Per org visibility settings | Per org visibility settings | All | All |
get_pending_leave_approvals | Flagged approvers only | Department | All | All |
approve_or_reject_leave | Flagged approvers only | Department | All | All |
get_time_tracking_status | Own | Department | All | All |
clock_action | Yes | Yes | Yes | Yes |
query_time_entries | Own | Department | All | All |
query_expenses (own) | Yes | Yes | Yes | Yes |
query_expenses (others) | No | Department | All | All |
get_expense_approvals | Direct reports only | Department | All | All |
approve_or_reject_expense | As assigned approver or manager | Department | All | All |
mark_expense_paid | No | No | Yes | Yes |
get_team_members | Yes | Department | All | All |
get_user_profile | Own | Department | All | All |
get_departments | Yes | Yes | Yes | Yes |
get_org_info | Yes | Yes | Yes | Yes |
get_public_holidays | Yes | Yes | Yes | Yes |
get_dashboard_stats | No | No | No | Yes |
create_shift | No | Department | All | All |
create_shifts | No | Department | All | All |
publish_schedule | No | No | Yes | Yes |
generate_leave_report | No | Department | All | All |
generate_timesheet_report | No | Department (no cost figures) | All | All |
Tool annotations & risk levels
Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and a risk level. Hosts use these to decide when to prompt you before acting — high-risk tools (deletes, offboarding, payouts, publishing) are flagged so the AI confirms the specific record with you before calling them. The Tools Reference shows the badge for each tool.
Best Practices
Account security
- Use a strong, unique password for your BookYourPTO account
- Enable two-factor authentication (2FA) for an additional layer of security
- Do not share your credentials with others — each user should log in with their own account
- If you suspect your session is compromised, change your password in BookYourPTO immediately
Network security
- The hosted MCP server communicates with the BookYourPTO API over HTTPS
- All traffic is encrypted in transit (TLS)
- The MCP server is not directly reachable from the internet: it runs on a private container network, and public traffic reaches it only through a reverse proxy that terminates TLS
- Only the public status check is exposed; the server's internal health and diagnostics endpoints are refused from the internet
/mcpenforces an Origin allow-list, so a web page on another site cannot call it from a visitor's browser
Data handling
- The MCP server does not persist any data — tokens and cache are held in memory only and destroyed when your session ends
- Per-user sessions are isolated: your data is never visible to other connections
- All data flows through the BookYourPTO API, which enforces access controls
- Receipt tools (
analyze_receipt,upload_expense_receipt) take the file itself as base64 in the tool call. The server never fetches a file from a URL on your behalf - AI clients may retain conversation history — refer to your AI provider's data policies
Logging
- The server writes structured JSON logs, one line per event, each tagged with a request id
- Every tool call is logged with the tool name, outcome, duration and the signed-in user and organization ids — never an email address or name
- Tool arguments are summarised, not recorded: each argument is logged by name with its type, string arguments by their length only, so the text you send (names, notes, reasons, file contents) never reaches the log. Numeric and true/false arguments are recorded as given
- A failed call is logged by its HTTP status and error code, not by its message, which could name a person
- Keys that look sensitive (passwords, tokens, emails, phone numbers, names, addresses, salaries) are redacted from every log line as a further safeguard
Health checks
GET /healthis public and answers only whether the server is up:{"status":"ok"}with HTTP 200, or{"status":"unavailable"}with HTTP 503. It never reveals dependency names, versions, hosts or timings, and responses are not cached- The server also has internal operations endpoints used by its own deployment and monitoring. They are not part of the public interface