Troubleshooting
Common MCP connection, authorization, and tool-call errors, and how to resolve them.
Connection issues
Claude Desktop says "Could not connect"
- Confirm the URL is
https://mcp.vacationtracker.io. The olderhttps://mcp.vacationtracker.io/mcpstill works. Opening the URL in a browser shows the docs, not the MCP endpoint, so a page loading there doesn't prove the connection works. - Check your firewall allows outbound HTTPS to
mcp.vacationtracker.ioandauth.vacationtracker.io. - If your organization uses a proxy with SSL inspection, MCP clients usually fail the TLS handshake. Add both domains to the proxy's bypass list.
The OAuth consent screen never loads
Your MCP client must support PKCE (S256) on the authorization code flow, and one of these:
- RFC 7591 Dynamic Client Registration, with RFC 9728 protected resource metadata discovery and RFC 8414 authorization server metadata discovery, or
- a client ID and secret that you enter yourself.
All mainstream clients (Claude Desktop, Claude Code, Cursor, GitHub Copilot, Microsoft Copilot Studio) register themselves. If your client asks for a pre-registered client ID, create a client ID and secret in Vacation Tracker under Integrations → MCP and enter the authorization URL, token URL, client ID, secret, and scopes it shows you. See Setup → Client ID and secret. In Copilot Studio, this is the Manual type; Dynamic discovery needs no client ID.
"You can't connect to this tool"
The sign-in screen shows this when you signed in through a client you are not allowed to use. A personal client works only for the person who created it, and a company client only for people in the company that created it. The message names the owner or the company. Nothing is granted.
Ask the owner or your admin to set up the tool for you, or create your own personal client under Integrations → MCP.
Connected, but no tools appear
Your tool shows Vacation Tracker as connected but lists no tools. This usually means the Scopes field was left empty when you set up the client ID and secret, so the token grants no access. Enter the scopes shown when you created the client (for example mcp:workspace:read mcp:users:read mcp:leaves:read for read only), then disconnect and connect again.
MCPOAuthError: Incompatible authorization server
In full: "authorization server advertised an issuer that does not match the URL its metadata was discovered from (RFC 8414 §3.3); refusing to connect". GitHub Copilot and other clients that enforce §3.3 abort here, before the consent screen opens.
Vacation Tracker publishes a matching issuer, so a current client connects. If you see this error, your client is holding a cached copy of the old metadata document, which is served with Cache-Control: max-age=3600. Wait an hour, or remove and re-add the server to force a fresh discovery.
Copilot Studio: selecting Create does nothing
The dialog stays open and no connector appears. Check the Server URL field for a "Enter the complete server path to continue" message: the form has rejected the URL, so Create has nothing to submit. See Setup → Microsoft Copilot Studio for the two usual causes.
HTTP errors
401 invalid_token
The request had no Bearer token, or the token is invalid or expired. The response carries a WWW-Authenticate header pointing to the protected resource metadata, so clients normally refresh or restart the OAuth flow on their own. If you keep seeing 401s after a successful OAuth flow:
- Disconnect the Vacation Tracker connector in your AI client's settings.
- Reconnect and complete the consent screen.
- If the problem persists, contact
developers@vacationtracker.iowith the error message from your client's logs.
403 insufficient_scope
The token does not include the scope the tool needs, for example calling request_leave after granting only the read scopes. The response carries a WWW-Authenticate: Bearer error="insufficient_scope" challenge naming the scopes the token needs: the ones already granted plus the missing one. Clients that support step-up authorization reopen the consent screen; approve it and the call is retried. Otherwise, reconnect the connector as described in Scopes → Enabling write tools in your AI assistant.
If you granted the scope and still can't use the tool, your role is the limit, not the token: regular employees and approvers cannot use mcp:users:write or mcp:workspace:write (see Role ceiling).
403 paid plan required
MCP is available on all paid plans. A company that is not on a paid plan gets HTTP 403 on every request, with a JSON-RPC error body whose error.data.code is MCP_PAID_PLAN_REQUIRED. Upgrade to a paid plan and reconnect.
The same 403 response with error.data.code set to USER_INACTIVE means your Vacation Tracker user is deactivated. Ask an administrator to reactivate you.
Tool errors
A tool that fails returns a normal tool result with isError: true and an error object with a stable code, a message, a resolution, and optional details (see Tools → Errors). Assistants usually follow the resolution on their own. Common codes:
| Code | Meaning | What to do |
|---|---|---|
FORBIDDEN | Your role cannot do this or cannot see that record, for example another location's holidays as a regular employee. | Nothing to fix in the client; ask an administrator if you need the access. |
NOT_FOUND, USER_NOT_FOUND | The record does not exist or is not visible to you. | Check the id, or look it up with get_leaves or find_users. |
Ambiguous name (with candidates) | A name matched more than one record, for example "Eng" matching both "Engineering" and "Engineering Leads". | Retry with one of the candidate ids. |
INVALID_DATE | A date is not YYYY-MM-DD or a supported shortcut. | Use an ISO date or one of the shortcuts listed in Tools. |
VALIDATION_ERROR, VALIDATION_FAILED | The arguments or the API v2 request body are invalid. details lists the fields. | Correct the listed fields. |
MISSING_FIELDS | A manage_user action is missing the fields it needs. details.missing lists them. | Provide the listed fields. |
AUTOMATION_OVERRIDE_REQUIRED | A leave request triggers automation warnings. | Show the warnings to the user; resubmit with overrideAutomations only if they agree. |
INSUFFICIENT_SCOPE | The action needs a permission your role's scopes don't include. | See Role ceiling. |
INTERNAL_ERROR | An unexpected server-side failure. The full details are logged server-side. | Retry once; if it persists, report it (see below). |
The support block on every tool error points to developers@vacationtracker.io and the feature request form. Every failed call is logged server-side with a request ID, so we can trace an incident from the tool name and an approximate timestamp.
A section says "unavailable"
get_workspace_info, get_user_details, and get_workspace_settings mark a section unavailable when your role cannot read it, instead of failing the whole call. This is expected: regular employees, for example, cannot see departments or location work weeks.
Pending writes
A write tool that answers "status": "pending" did not fail. Vacation Tracker accepted the change but was still processing it after about 20 seconds. Wait a few seconds and check the result with the matching read tool (get_leaves for leave and TOIL, get_user_details for users, get_workspace_info or get_workspace_settings for workspace changes).
Do not submit the same change again: it is already queued, and a second submit can create a duplicate request. If the change still hasn't appeared after a minute, contact developers@vacationtracker.io with the operationId from the answer.
Feature requests
If you need a tool that doesn't exist yet, submit it via the feedback_url in the support block, or email developers@vacationtracker.io directly.