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 via SSE
2. The MCP server returns an OAuth challenge — your AI client 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 for a short-lived JWT access token
5. Tokens are automatically refreshed for the duration of your session
6. All tool calls run with your identity and permissions

AI Client                MCP Server               BookYourPTO
   │                        │                        │
   │── GET /sse ───────────►│                        │
   │◄── 401 (OAuth) ────────│                        │
   │                        │                        │
   │── Browser opens ──────►│── redirect ───────────►│
   │                        │                        │── User logs in
   │◄── code + state ───────│◄── redirect ───────────│   (browser)
   │                        │                        │
   │── POST /token ────────►│── proxy ──────────────►│
   │◄── access_token ───────│◄── tokens ─────────────│
   │                        │                        │
   │── GET /sse + Bearer ──►│                        │
   │◄══ SSE connected ══════│                        │

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

Self-hosted mode

For local development or self-hosted deployments, you can pre-authenticate with a shared service account by setting BYPTO_EMAIL and BYPTO_PASSWORD environment variables. In this mode, all connections share the service account's identity and no browser login is required.

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.

Role hierarchy

Tool permissions by role

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

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

Self-hosted deployments

• Store shared credentials (if using shared mode) in environment variables, not in code
• Use Docker secrets or a .env file with restricted permissions (chmod 600)
• Run the MCP server on a private network if possible
• Keep the MCP server image up to date for security patches