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, HR, and more.

Claude.ai (Custom Connector)

The simplest way to use BookYourPTO from Claude on the web or desktop.

1. In Claude.ai, go to Settings → Connectors
2. Click Add custom connector
3. Enter the MCP endpoint:

   https://mcp.bookyourpto.com/mcp
   

4. Claude runs the OAuth flow against your BookYourPTO instance — a browser window opens for you to sign in
5. Once authorized, the BookYourPTO tools appear in your Claude conversations

Claude Code

Run this command in your terminal:

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

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 and to trigger the browser sign-in.

Cursor

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

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

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": "http",
      "url": "https://mcp.bookyourpto.com/mcp"
    }
  }
}

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.

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/mcp"
    }
  }
}

4. Save and restart Windsurf

ChatGPT

1. Open ChatGPT → Settings → Connectors (or start a conversation and use the connectors menu)
2. Add a new MCP server and enter the URL:

https://mcp.bookyourpto.com/mcp

3. Name it BookYourPTO and save

Claude Desktop

Use the mcp-remote bridge to connect Claude Desktop to the hosted server over Streamable HTTP with the browser OAuth flow:

{
  "mcpServers": {
    "bookyourpto": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.bookyourpto.com/mcp"]
    }
  }
}

Edit this via Settings → Developer → Edit Config (claude_desktop_config.json), then restart Claude Desktop. A browser window opens for you to sign in.

Verifying the Connection

After connecting, try asking your AI assistant:

"What's my leave balance?"

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

Troubleshooting

Connection refused or timeout

• Verify the server URL is correct: https://mcp.bookyourpto.com/mcp
• Check your internet connection

Tools not appearing

• Restart your AI client after adding the MCP server
• Check the MCP server status: curl https://mcp.bookyourpto.com/health
• Confirm your client uses Streamable HTTP (type: "http" / --transport http), not the legacy SSE transport

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)