Scopes
MCP scopes, how they map to Vacation Tracker roles, and step-up consent for write scopes.
MCP has its own scopes, separate from the Zapier ones. Each scope unlocks a family of tools. AI clients usually request all of them on the consent screen so every tool is available, but you can grant a subset, for example only the read scopes.
Available scopes
| Scope | Allows | Tools |
|---|---|---|
mcp:workspace:read | View departments, locations and work weeks, leave types, labels, public holidays, leave policies, automations, notifications, and scheduled reports | get_workspace_info, get_holidays, get_workspace_settings |
mcp:users:read | Look up users and view their profiles, labels, balances, and quotas | find_users, get_user_details |
mcp:leaves:read | View leave and TOIL requests, exactly as your wallchart shows them | get_leaves |
mcp:leaves:write | Request, edit, cancel, delete, approve, and deny leave and TOIL | request_leave, update_leave, decide_leave |
mcp:users:write | Update users' profiles, departments, locations, labels, location admin rights, work weeks, and quotas | manage_user |
mcp:workspace:write | Change departments, locations, holidays, labels, leave types, leave policies, automations, notifications, and scheduled reports | manage_organization, manage_leave_setup, manage_automations |
Role ceiling
Scopes decide which tool families the token may use. They never override your Vacation Tracker role: the scope enables the tool, and your role caps what it can read and change. The server loads your role on every request and applies it in two places.
Which scopes your role can use. A granted scope that your role cannot use is ignored:
| Role | Usable scopes |
|---|---|
| User | The three read scopes and mcp:leaves:write |
| Approver | The three read scopes and mcp:leaves:write |
| Location admin | All six |
| Admin | All six |
So a regular employee who grants mcp:workspace:write still cannot change workspace settings, and never sees the manage_* tools.
What each action can reach. Inside a usable scope, every read and write follows the same rules as API v2 for your role (leave and TOIL lists follow the web app's wallchart). A regular employee with mcp:users:read only sees their own profile; an approver with mcp:leaves:write can decide only the requests they approve; only Admins manage labels, leave types, and automations. See Permissions for what each role sees.
Tools also have a minimum role: decide_leave needs Approver, and the manage_* tools need Location admin. Tools above your role are not listed.
Step-up consent
You don't have to grant every scope up front. If you connected with only the read scopes, the write tools your role can use stay listed. When the assistant calls one, the server answers HTTP 403 with a WWW-Authenticate: Bearer error="insufficient_scope" challenge. The challenge names every scope the new token needs: the ones you already granted plus the missing one, so approving it never removes access you had. MCP clients that support step-up authorization then open the Vacation Tracker consent screen again. After you approve, the client retries the call with the new token.
Clients that don't support step-up show an error instead. Reconnect the Vacation Tracker connector as described in Enabling write tools in your AI assistant.
Existing connections can request the write scopes without re-registering the client.
Granted scopes belong to your Vacation Tracker user, not to a single connection. Your latest consent in any MCP client replaces the previous grant, and your other MCP connections pick it up the next time they refresh their token.
Enabling write tools in your AI assistant
Connections made before the write tools existed have only the read scopes. Here is how to grant the write scopes in each assistant. Menu names come from each vendor's documentation and may change.
Claude (claude.ai, Claude Desktop, mobile)
- Go to Customize → Connectors and open the Vacation Tracker connector.
- Disconnect it, then connect it again.
- Approve the permissions on the Vacation Tracker consent screen.
Write tools are available in new chats. Claude's help center recommends the same disconnect-and-reconnect step when a connector's permissions change.
Claude Code
When a write tool fails with a needs additional permissions message, run /mcp, select the Vacation Tracker server and choose Re-authenticate. If you pinned oauth.scopes in your MCP configuration, add the write scope there first, or the new token still won't include it. For a connector you added in claude.ai, reconnect it at claude.ai/customize/connectors instead.
ChatGPT
- Open Settings → Apps (called Plugins on some accounts) and select Vacation Tracker.
- Select Reconnect if it is shown. Otherwise open the more-options menu (•••), select Disconnect, and connect again.
- Review the requested access and approve it on the Vacation Tracker consent screen.
In developer mode, select Refresh on the app after Vacation Tracker adds new tools, so ChatGPT picks them up.
Grok
Custom MCP connectors are managed at grok.com/connectors. xAI's documentation doesn't describe reconnecting a custom connector, so if the write tools fail, remove the Vacation Tracker connector and add it again (New Connector → Custom, then the Vacation Tracker MCP URL), and approve the consent screen. In the Grok CLI, open /mcps and authenticate the server again.
Gemini
Google documents custom MCP servers for the Gemini CLI and Gemini Enterprise:
- Gemini CLI: run
/mcp auth <server-name>with the name you gave the Vacation Tracker server. - Gemini Enterprise: select Actions → Reload custom actions to authenticate again.
Other MCP clients
Clients that implement MCP step-up authorization ask for the new permissions on their own. For any other client, disconnect and reconnect the Vacation Tracker server.
Default scope
If a public MCP client omits the scope parameter, the authorization server offers every MCP scope (plus openid, profile and email), and you see all of them on the consent screen. Confidential OAuth clients that omit it get openid only.
Requesting scopes
MCP clients discover and request scopes through the standard OAuth flow. Nothing to configure on the client side. Multiple scopes are space-delimited when URL-encoded:
scope=mcp:workspace:read%20mcp:users:read%20mcp:leaves:read%20mcp:leaves:writeRevoking scopes
Scopes are granted per authorization. To change what a connected client is allowed to do, revoke it and reconnect, which prompts a fresh consent screen. See Setup → Revoking access for how to revoke today. A self-service page is on the roadmap.