Security

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

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

  1. Your AI client connects to the MCP server over Streamable HTTP (POST /mcp)
  2. Unauthenticated requests get a 401 pointing at the server's OAuth metadata; your client discovers the endpoints and opens a browser window
  3. You sign in on BookYourPTO's login page (supports email/password and two-factor authentication)
  4. BookYourPTO issues an authorization code, which is exchanged — with PKCE (S256) — for a short-lived JWT access token
  5. Tokens are refreshed automatically for the duration of your session
  6. 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 ═══════│                        │
Your password never leaves BookYourPTO. The AI client only receives an access token — it cannot see, store, or transmit your credentials. Each connection is fully isolated.

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)
  • /mcp is 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 initialize handshake. The server can also run in a strict mode that refuses any later request without a matching MCP-Protocol-Version header.
  • 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

RoleLevelDescription
EMPLOYEEBasicView own data only
DEPARTMENT_HEADManagerView/manage own department
ADMINISTRATORAdminFull access to all features
EXECUTIVEExecutiveFull 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.

ToolEMPLOYEEDEPT_HEADADMINEXECUTIVE
query_leaves (own)YesYesYesYes
query_leaves (others)Per org visibility settingsPer org visibility settingsAllAll
create_leave_requestYesYesYesYes
get_leave_balance (own)YesYesYesYes
get_leave_balance (others)Per org visibility settingsPer org visibility settingsAllAll
get_pending_leave_approvalsFlagged approvers onlyDepartmentAllAll
approve_or_reject_leaveFlagged approvers onlyDepartmentAllAll
get_time_tracking_statusOwnDepartmentAllAll
clock_actionYesYesYesYes
query_time_entriesOwnDepartmentAllAll
query_expenses (own)YesYesYesYes
query_expenses (others)NoDepartmentAllAll
get_expense_approvalsDirect reports onlyDepartmentAllAll
approve_or_reject_expenseAs assigned approver or managerDepartmentAllAll
mark_expense_paidNoNoYesYes
get_team_membersYesDepartmentAllAll
get_user_profileOwnDepartmentAllAll
get_departmentsYesYesYesYes
get_org_infoYesYesYesYes
get_public_holidaysYesYesYesYes
get_dashboard_statsNoNoNoYes
create_shiftNoDepartmentAllAll
create_shiftsNoDepartmentAllAll
publish_scheduleNoNoYesYes
generate_leave_reportNoDepartmentAllAll
generate_timesheet_reportNoDepartment (no cost figures)AllAll

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
  • /mcp enforces 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 /health is 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