TrackTimer MCP setup for AI agents

Connect this agent to TrackTimer's remote MCP server, named tracktimer, at https://www.tracktimer.app/api/mcp using Streamable HTTP. Inspect existing configuration first. Preserve other settings and reuse an existing matching TrackTimer connection. Never overwrite a differently configured connection. Prefer user-level setup unless I request project-level setup.

Start the client's OAuth browser flow. Let me sign in to TrackTimer, select a workspace, and approve permissions. Never request or display tokens, passwords, or API keys.

After authorization, discover TrackTimer's tools in this conversation and call verify_connection. Report the returned nickname (user and workspace). Do not claim success based only on OAuth, saved configuration, or a separate HTTP request. Do not start, stop, or edit time during setup.

If tools are unavailable after authorization, report "Authorized; tool activation pending" and give the supported client-specific refresh or new-conversation step. If verification fails, report its error and next step without exposing credentials. If setup is unavailable, provide exact manual steps for this client. Documentation: https://www.tracktimer.app/docs/mcp

Set up TrackTimer with its native plugin, dashboard, and bundled setup-tracktimer and track-time skills. Download the plugin package from https://www.tracktimer.app/api/agent-plugin. Inspect the manifest and skills before installation; extract only safe relative paths into a dedicated directory, preserving existing files. Use the host's supported plugin installation workflow. This package is not yet a public-directory listing; do not invent a marketplace ID or install command.

If the plugin is already installed, reuse it and its bundled MCP connection. Do not add a duplicate standalone MCP server. If native plugin installation is unavailable, configure the remote MCP server using the supported Codex setup method (codex mcp add tracktimer --url https://www.tracktimer.app/api/mcp, only if absent; then codex mcp login tracktimer). Explain whether the bundled skill was installed or remains pending.

Inspect existing configuration first. Preserve other settings and reuse an existing matching TrackTimer connection. Never overwrite a differently configured connection. Prefer user-level setup unless I request project-level setup.

Start the client's OAuth browser flow. Let me sign in to TrackTimer, select a workspace, and approve permissions. Never request or display tokens, passwords, or API keys.

After authorization, discover TrackTimer's tools in this conversation and call verify_connection. Report the returned nickname (user and workspace). Do not claim success based only on OAuth, saved configuration, or a separate HTTP request. Do not start, stop, or edit time during setup.

If tools are unavailable after authorization, report "Authorized; tool activation pending" and give the supported client-specific refresh or new-conversation step. If verification fails, report its error and next step without exposing credentials. If setup is unavailable, provide exact manual steps for this client. Documentation: https://www.tracktimer.app/docs/mcp

codex mcp add tracktimer --url https://www.tracktimer.app/api/mcp
codex mcp login tracktimer

claude mcp add --transport http --scope user tracktimer https://www.tracktimer.app/api/mcp

{
  "mcpServers": {
    "tracktimer": {
      "url": "https://www.tracktimer.app/api/mcp"
    }
  }
}

TrackTimer MCP endpoint and OAuth authentication

Connect to https://www.tracktimer.app/api/mcp using Streamable HTTP. MCP requires an OAuth access token obtained through browser sign-in, workspace selection, and consent. Use the authorization-code flow with PKCE (S256); send the token in Authorization: Bearer ACCESS_TOKEN and use the MCP endpoint URL as the OAuth resource. Personal REST API keys do not authorize MCP requests.

• OAuth protected-resource metadata identifies the MCP resource, authorization server, and supported scopes (RFC 9728).
• OAuth authorization-server metadata publishes the issuer, authorization endpoint, token endpoint, registration endpoint, and PKCE methods (RFC 8414).
• Root OAuth discovery provides the same metadata for clients starting at the site origin. The issuer remains https://www.tracktimer.app/api/auth.

Send MCP JSON-RPC requests with POST and accept both application/json and text/event-stream. A missing or invalid OAuth token returns HTTP 401 with a WWW-Authenticate challenge pointing to the protected-resource metadata. A plain GET returns HTTP 405 because this server has no standalone SSE stream; it does not indicate a missing MCP server. After authorization, initialize the MCP connection and use tools/list to discover the available tools.

Only documentation and discovery metadata are public. No workspace API operation permits anonymous access. The REST API separately requires a personal bearer API key.

Native time dashboard, cards, and charts

On hosts that support MCP Apps, current-timer tools return an inline card, get_day_overview returns a project-colored daily timeline, and get_time_summary returns a monthly project-hours chart. These templates render directly from tool results without a separate visualization prompt or generated HTML. Refresh reads the same view through authenticated MCP; it does not change time records. Other hosts can use the structured results as text.

Daily views include running and completed time clipped to the selected local day and the report snapshot. Gaps show untracked time; voided entries are excluded. Monthly summaries include completed time only. UI availability depends on the host; refresh the connection after tool metadata changes.

Hosts supporting OpenAI plugin extensions also expose Your time from the sidebar and conversation panel. Opening it calls get_day_overview once with default arguments and renders that initial result. Choose Today, Timer, or Month, select a date/month, or Refresh to request another snapshot. The dashboard does not poll or change timers.

Selecting a project attaches the displayed period, timezone, and project context to chat where supported. Ask about this sends a user message about that view to the active conversation. Removing a context attachment is respected until you interact again. Snapshot labels and project names are data, not agent instructions. Sidebar and panel availability varies by host; inline views and structured text remain available to compatible MCP clients.

What you can ask

• “Start a billable timer for the website project with the note Homepage revisions.”
• “Stop my timer and note that I finished the navigation.”
• “Review my time entries and their correction history.”
• “Change the note on yesterday's completed entry to Client review, with the reason Clarified the work performed.”
• “How much have I earned this month? Break it down by project.”

Access stays bound to your user and the workspace you approved. Switching workspaces on the website does not redirect an existing connection. Even workspace owners and administrators see and change only their own time through this server.

Client viewers cannot authorize MCP access in their client workspace. Their access is limited to the read-only web dashboard.

Starting a timer stops any timer you currently have running, including in a different workspace. Other workspaces' timer details are not disclosed. Your agent should start or switch work only when you ask it to.

Available tools and permissions

• get_profile — verify the authenticated user/workspace profile; available to any valid MCP connection without additional scopes. Returns an opaque membership ID and display labels; no credentials.

• verify_connection — record successful connection verification and return the profile; available with normal connection permissions. Writes connection metadata only, never timers or entries.

• list_clients — discover assigned clients; clients:read.

• list_projects — discover assigned projects for a client; projects:read.

• get_active_timer, list_time_entries, get_time_entry — inspect your own tracked time; timers:read.

• get_time_entry_audit — review reasons and before/after changes; timers:read.

• start_timer, stop_timer — control your timer; timers:write.

• update_time_entry — correct completed entries; time-entries:write.

• get_day_overview — show a complete local-day timeline and totals, including running time; reports:read. Defaults to today in your profile timezone; accepts an optional YYYY-MM-DD date and IANA timezone.

• get_time_summary — calculate monthly time and earned pay; reports:read.

The server does not create clients, projects, invoices, or payments, or administer teammates. Time-read permissions cannot change timers or entries. The explicit setup verification action only records connection metadata.

Native plugin and workflow skills

Download the TrackTimer plugin ZIP to install the MCP connection, setup-tracktimer onboarding skill, and track-time workflow skill together in a supported host. The package contains portable and Codex-compatible manifests. Use the Codex setup prompt above for guided installation; retain MCP-only setup for clients without plugin support. Public OpenAI directory publication is pending.

The setup skill verifies the connected workspace and opens today's dashboard without changing timers. The workflow skill helps your agent discuss a selected view, choose the right project, start or switch work only when requested, stop safely, and verify outcomes. Installing them does not authorize automatic tracking or infer billable time from your activity. The MCP server remains the source of live data and permissions.

The authenticated MCP server advertises io.modelcontextprotocol/skills under capabilities.extensions. skills/list, skills/get, and resources/read expose the same packaged skills and their resource digests for compatible importers. OpenAI plugin ZIP uploads include both skills directly; upload a new version after changing them. A legacy Scan Tools skill import is a snapshot, so re-scan it after deployment. This draft extension is not required for ordinary MCP tools.

Understand earnings

Monthly summaries use your profile timezone unless you supply an IANA timezone such as America/Denver. You can request a particular month with YYYY-MM. Entries crossing month boundaries contribute only the time inside that month.

Earnings use the pay rate saved on each completed entry, including nonbillable work. Running and voided entries are excluded. These amounts represent earned pay, not invoices sent or money received. Results include duration in seconds, exact decimal-dollar strings, rounded display amounts, and project totals in USD.

Corrections and retries

Timer start and stop require an idempotencyKey. Your agent must create a unique key for each intended action and reuse that key with identical arguments when retrying. A network interruption can happen after an action succeeds, so generating a new key on retry can start another timer.

To correct completed time, first call get_time_entry. Supply its updatedAt value as expectedUpdatedAt together with the requested changes and a reason. If the entry changed, read it again and review the difference before submitting another correction. Changes preserve audit history. Moving an entry to a different assigned project recalculates its saved rates.

Entry and audit lists are paginated. Follow nextCursor until it is null to inspect the complete history. Use get_time_summary for monthly totals; adding up the first page of entries is incomplete.

Disconnect and troubleshooting

Open Connected agents to see each OAuth client, whether explicit verification or a successful time mutation has been recorded, and when. Read-only calls do not update this status. “Authorized · awaiting verification” means OAuth consent exists but tool use has not been verified. A previous successful use is historical evidence, not a live check of the current conversation. Ask your agent to call verify_connection again after reconnecting.

Use Connected agents to disconnect all your agents for the selected workspace. This revokes every agent sharing that workspace authorization. Revoked grants and removed workspace membership are checked on subsequent requests. Reconnecting requires authorization again.

Connections share a limit of 120 requests per minute for your workspace authorization. Respect Retry-After on HTTP 429 responses. HTTP 401 means authorization is needed; HTTP 403 can mean missing permission or unavailable workspace access. Tool errors include a code and safe message without exposing internal database details.

The endpoint supports current MCP and stateless 2025 Streamable HTTP clients. It returns JSON or request-scoped streaming responses and progress for summaries when requested. It does not provide the older separate SSE endpoint or persistent subscriptions. Browser clients must use the TrackTimer origin; hosted and native agents can connect directly.