TickM

MCP troubleshooting

Diagnose connection failures, plan/role errors, token expiry, and redirect URI issues.

For setup instructions, see MCP (AI assistants). For data handling and token retention, see the MCP Privacy Policy.

This guide helps you diagnose common MCP connection and tool-call failures. TickM MCP server and registration errors are quoted below as returned by the API so you can search for them in your AI client's logs. OAuth token refresh failures vary by client — typical examples are shown where relevant.

Plan not eligible (Pro required)

MCP is included on Pro and Enterprise only. Basic and Team organizations cannot use MCP.

At connection time (HTTP 402)

Your AI client may show a JSON error like:

{
  "error": "plan_limit_exceeded",
  "feature": "McpAccess",
  "currentPlan": "team",
  "upgradeRequired": true,
  "upgradeUrl": "/manage/subscription"
}

What to do: Upgrade the organization to Pro in the TickM app under Manage → Subscription, or ask your org admin to upgrade. See upgrading your tier.

During a tool call

MCP access is not available on the 'team' plan. Upgrade to Pro at /manage/subscription to use TickM's MCP tools.

What to do: Same as above — the connected org is not on a plan that includes MCP. The plan name in the message reflects your current tier (basic, team, etc.).

Manager role required

Some tools — creating or editing projects and clients, or searching another user's time entries — require the Manager role.

Only managers can create projects.

Similar messages appear for other manager-only actions, for example:

  • Only managers can edit projects.
  • Only managers can create clients.
  • Only managers can search another user's time entries.

What to do: Ask your org admin to grant you the Manager role, or use a manager-only tool only when signed in as a manager. Standard users can still use time-entry tools on their own entries.

Clients feature not on plan

Client-related MCP tools require the org's Clients feature (Team plan and above).

Assigning a client to a project is not available on the 'basic' plan. Upgrade to use clients.

What to do: Upgrade to Team or higher if you need client management via MCP, or avoid client-related tools (create_client, edit_client, assigning clientId on projects).

Expired or idle OAuth session

MCP connectors use rotating refresh tokens with a 14-day idle limit and a 30-day absolute lifetime. When either limit is reached, the connector must re-authorize.

When a refresh token has expired, your AI client may show an OAuth error such as:

error: "invalid_grant"
error_description: "Unknown or invalid refresh token."

Some clients skip the error details and simply prompt you to sign in again.

What to do:

  1. Disconnect or remove the TickM MCP connector in your AI app.
  2. Re-add the connector pointing at https://app.tickm.com/api/mcp.
  3. Complete the OAuth consent screen (“TickM MCP”) again.

See also the MCP Privacy Policy for token retention details.

Redirect URI not allowlisted

During OAuth client registration, TickM only accepts loopback redirect URIs (for desktop clients) or pre-approved hosted-connector URIs (for AuditionAI, claude.ai, ChatGPT, etc.).

error: "invalid_redirect_uri"
error_description: "Only http://127.0.0.1, http://localhost, http://[::1] (any port), or a pre-approved hosted-connector redirect URI are accepted."

What to do:

  • Desktop / local clients — use a loopback callback such as http://127.0.0.1:PORT/callback or http://localhost:PORT/callback. Do not use HTTPS loopback or custom domains.
  • Hosted connectors — the connector's redirect URI must be on TickM's trusted allowlist. Contact [email protected] if you are integrating a new hosted MCP client.

Other common errors

No organization context

No organization context resolved for this request. Connect to /api/mcp (defaults to your earliest organization membership), or pin an org with ?orgSlug={slug} / /api/mcp/o/{slug} from Manage → AI Assistant (MCP).

What to do: If you belong to multiple orgs, add ?orgSlug=your-slug to the MCP URL, or use the org-specific endpoint shown in Manage → AI Assistant (MCP).

Could not resolve authenticated user

Could not resolve the authenticated user for this request.

What to do: Re-authenticate. Your OAuth token may be invalid or the session may have expired — follow the steps in “Expired or idle OAuth session” above.

Still stuck?

Email [email protected] with the exact error message, your AI client (AuditionAI, Claude Desktop, Cursor, etc.), and the MCP endpoint URL you configured.