Connecting

This guide walks you through connecting your AI tool to BookYourPTO using the Model Context Protocol (MCP). Once connected, your AI assistant can manage leaves, time tracking, expenses, and more.

Claude Code

Run this command in your terminal:

claude mcp add --transport sse bookyourpto https://mcp.bookyourpto.com/sse

Use the --scope flag to control where the server is available:

• --scope local (default) — Available only to you in the current project
• --scope project — Shared with your team via .mcp.json file
• --scope user — Available to you across all projects

Use the /mcp command inside Claude Code to list and manage your MCP servers.

Cursor

1. Open Cursor Settings → MCP → Add new global MCP server
2. Paste the following configuration:

{
  "mcpServers": {
    "bookyourpto": {
      "url": "https://mcp.bookyourpto.com/sse"
    }
  }
}

3. Save and restart Cursor

To share the configuration with your team, create a .cursor/mcp.json file in your project root with the same configuration.

VS Code (GitHub Copilot)

1. Create a .vscode/mcp.json file in your workspace:

{
  "servers": {
    "bookyourpto": {
      "type": "sse",
      "url": "https://mcp.bookyourpto.com/sse"
    }
  }
}

2. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run MCP: List Servers
3. Start the BookYourPTO server from the list

For user-level configuration (all workspaces), run MCP: Open User Configuration from the Command Palette and add the server configuration there.

Claude Desktop

Claude Desktop uses local stdio transport. You'll need Docker installed to run the MCP server locally.

1. Install Docker Desktop if you don't have it
2. Open Settings → Developer → Edit Config
3. Add the BookYourPTO server to your claude_desktop_config.json:

{
  "mcpServers": {
    "bookyourpto": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BYPTO_EMAIL=your-email@company.com",
        "-e", "BYPTO_PASSWORD=your-password",
        "bookyourpto/mcp-server:latest"
      ]
    }
  }
}

4. Replace your-email@company.com and your-password with your BookYourPTO credentials
5. Save and restart Claude Desktop

Windsurf

1. Open Windsurf Settings (Cmd+, on Mac) → search for MCP
2. Click View raw config to open mcp_config.json
3. Add the BookYourPTO server configuration:

{
  "mcpServers": {
    "bookyourpto": {
      "serverUrl": "https://mcp.bookyourpto.com/sse"
    }
  }
}

4. Save and restart Windsurf

ChatGPT

1. Open ChatGPT → Settings → Connected Apps or start a conversation and click the plug icon
2. Select Add MCP Server and enter the URL:

https://mcp.bookyourpto.com/sse

3. Name it BookYourPTO and save

Verifying the Connection

After connecting, try asking your AI assistant:

"What's my leave balance?"

Your browser will open a BookYourPTO login page. Sign in with your email and password (2FA supported). Once authenticated, the browser will close and your AI client will be connected. The AI will then call the appropriate tools and return results from your workspace.

Self-Hosting with Docker

You can run the MCP server yourself using the public Docker image. This is useful for teams that want full control or need to run the server on their own infrastructure.

docker pull bookyourpto/mcp-server:latest

docker run -d \
  --name bookyourpto-mcp \
  -e BYPTO_EMAIL=your-email@company.com \
  -e BYPTO_PASSWORD=your-password \
  -e MCP_TRANSPORT=http \
  -p 8000:8000 \
  bookyourpto/mcp-server:latest

Verify it's running:

curl http://localhost:8000/health

Then connect your AI client to http://localhost:8000/sse instead of the hosted URL.

Troubleshooting

Connection refused or timeout

• Verify the server URL is correct: https://mcp.bookyourpto.com/sse
• Check your internet connection
• If self-hosting, ensure the MCP server container is running

Tools not appearing

• Restart your AI client after adding the MCP server
• Check the MCP server status: curl https://mcp.bookyourpto.com/health

Browser login page doesn't open

• Some AI clients may not support OAuth automatically. Check that your client supports the MCP OAuth 2.0 flow
• Try disconnecting and reconnecting the MCP server

"Not authenticated" errors

• Your session may have expired. Disconnect and reconnect to trigger a new login
• Check that you successfully completed the browser login flow

Permission denied on tool calls

• The MCP server uses your own account permissions. Ensure your account has the appropriate role for the tool you're trying to use
• Some tools require ADMINISTRATOR or EXECUTIVE roles (see Security)