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

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 ═══════│                        │

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) and an MCP-Protocol-Version header guard.
• 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 346 tools, not just the examples below.

Role hierarchy

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 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 runs in a private subnet on AWS — it is not directly accessible from the internet
• External access is routed through an Application Load Balancer with an ACM certificate
• /mcp enforces an Origin allow-list and a protocol-version header check

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
• AI clients may retain conversation history — refer to your AI provider's data policies