MCP Server
Connect Claude Desktop, Cursor, and other AI clients to Vacation Tracker over the Model Context Protocol.
Vacation Tracker runs an MCP (Model Context Protocol) server at https://mcp.vacationtracker.io. MCP clients like Claude Desktop, Claude Code, and Cursor can use it from inside the AI chat, without opening Vacation Tracker: look up people, balances, leaves and holidays, book and approve leave, and change workspace settings.
The server reads and writes. Write tools wait for Vacation Tracker to finish the change and answer with the result, so the assistant knows whether the change went through. Every write is recorded in the user logs as done "via AI assistant (MCP)".
How it works
- Your AI client connects to
https://mcp.vacationtracker.io. - On first use, the client performs an OAuth2 authorization flow (RFC 8414 discovery, RFC 7591 Dynamic Client Registration, PKCE, authorization code) against
https://auth.vacationtracker.io. - You log in to Vacation Tracker and grant the requested scopes on the consent screen.
- The client exchanges the code for a Bearer token and calls MCP tools on your behalf.
- Each tool call is authorized against your Vacation Tracker role. Nobody sees or changes more through MCP than they can in the web app.
This is the standard MCP OAuth handshake. For most clients there's nothing to configure beyond the server URL: no API keys, no shared secrets.
Some tools, like Gemini Enterprise, don't register themselves and ask for a client ID and secret instead. You can create these in Vacation Tracker under Integrations → MCP: a personal client for yourself, or, as an admin, a company client for everyone in your company. See Setup → Client ID and secret.
Protocol versions
The server speaks MCP protocol 2026-07-28 and every 2025 revision (2025-03-26, 2025-06-18, 2025-11-25) over the Streamable HTTP transport. It is stateless: 2025-era clients that start with initialize and 2026-07-28 clients that send per-request metadata both work, and the server negotiates the version with each client.
Available tools
The server ships 13 tools. See Tools for parameters, examples and what each tool does not do.
| Tool | Scope | Minimum role | What it does |
|---|---|---|---|
get_workspace_info | mcp:workspace:read | Any | Departments, locations (optionally with work weeks), leave types, and labels |
find_users | mcp:users:read | Any | Search people by name or email, department, location, label, and status |
get_user_details | mcp:users:read | Any | One person (default: you): profile, labels, work week, balances, quotas, and the leave types they can request |
get_leaves | mcp:leaves:read | Any | Leaves and TOIL in a date range, or one by id, exactly as the person's wallchart shows them |
get_holidays | mcp:workspace:read | Any | Public holidays per location and year |
get_workspace_settings | mcp:workspace:read | Any | Leave policies per location, automations, notifications, and scheduled reports |
request_leave | mcp:leaves:write | Any | Preview or submit leave or TOIL for yourself or someone else |
update_leave | mcp:leaves:write | Any | Edit, cancel, or delete a leave or TOIL request |
decide_leave | mcp:leaves:write | Approver | Approve or deny a leave or TOIL request |
manage_user | mcp:users:write | Location admin | Profile, location, department, activation, labels, location admin, work week, and quotas |
manage_organization | mcp:workspace:write | Location admin | Departments, locations, location work weeks, holidays, and labels |
manage_leave_setup | mcp:workspace:write | Location admin | Leave types, and leave policies per location |
manage_automations | mcp:workspace:write | Location admin | Automations, notifications, and scheduled reports |
The client only lists the tools your role can use. A tool that needs a scope you have not granted yet stays listed; calling it asks you to grant that scope (see Scopes).
Tools accept names or IDs wherever a reference is expected, so "Engineering" works just as well as a department id. If a name is ambiguous, the tool returns an error with candidate matches and the assistant can retry with a specific one. Date shortcuts like today, this_week, next_month, and last_week resolve in your location's timezone.
Permissions
The MCP server has exactly the permissions of API v2 for your role, with two exceptions: leave and TOIL lists follow the web app's wallchart, so everyone sees exactly the team leave Vacation Tracker shows them, and everyone can read the leave policies of their own location. Writes also go through the same role, permission, and plan checks as the web app.
| Role | What you can read | Compared with the web app |
|---|---|---|
| Everyone | Leave and TOIL exactly as the wallchart shows them (visibility add-on, team, approver teams, substitutes, approver levels, reason and hidden leave type masking) | Same |
| Everyone | The leave policies of your own location | Same |
| User | Your own profile, balances and quotas; leave types (hidden ones masked); your own location's holidays | Narrower: no departments, locations, labels, or other locations' policies |
| Approver | Adds the users of the departments you approve for, and hidden leave type names | Narrower: no automations, notifications, or reports |
| Location admin | Adds your locations' users, departments, locations, policies, holidays, and notifications | About the same |
| Admin | Everything | Same |
Some writes are narrower than the tool's minimum role: for example, only Admins manage labels, leave types, and automations. A tool call that your role cannot perform returns an error explaining why. MCP never acts on behalf of another user: every change is made as you.
Prerequisites
- A Vacation Tracker account on a paid plan.
- An MCP-capable AI client. Claude Desktop is the reference client; Claude Code, Cursor, ChatGPT, Codex, GitHub Copilot, Microsoft Copilot Studio and Gemini Enterprise connect too, each covered in Setup. Any client that implements the MCP Streamable HTTP transport and OAuth2 PKCE with Dynamic Client Registration or a client ID and secret should work.
MCP is available to every Vacation Tracker account on a paid plan. There is no separate enablement step or feature flag.
Next steps
- Setup: connecting Claude Desktop and Cursor.
- Tools: full reference with parameters, examples, and error shapes.
- Scopes: what each scope grants, the role ceiling, and step-up consent.
- Troubleshooting: connection problems, HTTP errors, and tool error codes.