Help / Integrations

MCP and AI clients

Time Trakkr runs a Model Context Protocol (MCP) server, so you can point an AI client such as Claude, ChatGPT, Gemini CLI, Perplexity, Claude Code, or Cursor directly at your workspace. From there you can ask about tracked time and budgets, log time, run timers, and draft invoices in plain language — all governed by your role, the same as everywhere else in the app. The connection is set up from the Integrations page, in the Connect your AI (MCP) card.

The server URL

The card shows your Server URL, which is:

https://timetrakkr.com/api/mcp

Copy that URL; every client below needs it.

Connecting a client

Every client below signs in with OAuth: a Time Trakkr sign-in page opens, you approve, and the connection acts as you, with your role.

Claude (claude.ai or Claude Desktop)

Open Settings → Connectors → Add custom connector, paste the server URL, and sign in when prompted.

ChatGPT

Custom connectors need a paid ChatGPT plan (Plus, Pro, Business, or Enterprise).

  1. Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
  2. Go back and press Create. Name it Time Trakkr, paste the server URL, and choose OAuth for authentication.
  3. Confirm you trust it, press Create, and sign in to Time Trakkr.
  4. In a new chat, choose + → Developer mode → Time Trakkr to use it.

Gemini CLI

The Gemini CLI connects; the Gemini web app does not take custom MCP servers.

  1. Add Time Trakkr to ~/.gemini/settings.json:

    { "mcpServers": { "timetrakkr": { "httpUrl": "https://timetrakkr.com/api/mcp" } } }
    
  2. Start gemini and run /mcp auth timetrakkr. Your browser opens the Time Trakkr sign-in.

  3. After you approve, the browser shows a plain "Authentication Successful!" page on a localhost address. That page comes from the Gemini CLI on your own computer, which is how it receives the sign-in. Close it and go back to the terminal.

  4. Run /mcp to check that the Time Trakkr tools are listed.

Perplexity

Custom connectors need a paid Perplexity plan.

  1. Open Plugins in the sidebar, then Add custom → Add MCP connector → Remote.
  2. Name it Time Trakkr, paste the server URL, choose Streamable HTTP, and choose OAuth. Leave the client ID and secret empty; Perplexity registers itself.
  3. Save, connect, and sign in to Time Trakkr.
  4. Name the connector in your request, for example: "Using Time Trakkr, how many hours did I log this week?"

Or import the Time Trakkr plugin, which adds the same connector for you: open Plugins → Add custom → Import plugin from GitHub, paste https://github.com/time-trakkr/time-trakkr-plugin exactly as written (lowercase), then connect and sign in.

Claude Code

Run claude mcp add --transport http timetrakkr https://timetrakkr.com/api/mcp, then run /mcp to authenticate.

Cursor

Add the same server URL as a custom MCP server in Cursor's settings and authenticate when prompted.

When you sign in over OAuth, the consent screen lets you choose read-only or read/write access, so you decide up front whether the client may change anything.

OAuth versus an API key

There are three credentials that work, and they behave differently:

  • OAuth (recommended). The connection acts as you and carries your role. It can be read-only or read/write depending on what you approve on the consent screen. This is what the buttons above use.
  • An organization API key. Keys created on the Developer page also work as a Bearer header, but over MCP they are read-only and belong to the organization rather than a person. Use one when you want a machine to read data without acting as any individual.
  • A personal access token. It acts as you and carries your role, so a member's token sees what that member sees. Over MCP it is read-only, whatever scopes it was created with, and it needs the read scope. It stops working when its owner is deactivated. To change anything from an AI client, connect with OAuth.

Why it is safe

Every call is scoped to your workspace and follows the same rules as the rest of Time Trakkr:

  • Members never see rates or other money, in the AI client just as in the app. See roles and permissions for exactly who sees what.
  • Draft invoices are never sent automatically — the assistant can only create a draft for you to review and send yourself.
  • Access is revocable at any time. Revoke a personal access token, or a client you connected with OAuth, under Integrations; an organization key is revoked on the Developer page.

Limits

Each person can make 100 requests every 15 seconds, the same limit as the REST API; an organization key shares one allowance per workspace. Every message in a batch counts. Past the limit the server answers 429 with a Retry-After header giving the seconds to wait. Normal use of an AI client comes nowhere near it.

Service status

status.timetrakkr.com shows whether the app and the MCP server are up, with the history of any incident. It checks the server from outside every few minutes, so it reflects what a client sees. Planned maintenance is posted there in advance.

Versioning and changes

The server implements MCP protocol version 2025-06-18 and also accepts 2025-03-26 and 2024-11-05; the version is agreed when a client connects. New protocol versions are added beside the ones already supported rather than replacing them.

  • Additions need no notice. New tools, new optional parameters and new fields in results can appear at any time, so a client should ignore what it does not recognize.
  • Breaking changes get at least 90 days' notice. Removing or renaming a tool, changing a required parameter, dropping a supported protocol version or changing how sign-in works is announced at least 90 days ahead. A deprecated tool keeps working until then, and its description says it is deprecated and what replaces it.
  • Where changes are announced: under Settings → What's new in Time Trakkr, and in this article. Directory partners hear directly about anything breaking.

For working with the built-in assistant inside Time Trakkr rather than an outside client, see the AI assistant. For the plain REST API and webhooks, see the API and webhooks.

Updated 2026-11-09. Still stuck? Contact support or return to the Help Center.