Lucen Track MCP Server

Connecting to Lucen Track MCP

Connect your AI tool to Lucen Track using the Model Context Protocol (MCP). Once connected, your tool can read and write time entries, manage timers, and pull reports based on your account permissions.

Learn how to connect your favorite AI tools to Lucen Track to automate your time tracking, how to solve the most common connection issues, and the frequently asked questions on this integration and how it works.

If you have any other questions, comments or suggestions, feel free to contact us!

What you'll find in this article:

• Connection guide
• Troubleshooting
• FAQ

Quick reference

Server URL	https://track-api.lucensoftware.com/mcp
Transport	Streamable HTTP (recommended)
Authentication	OAuth 2.0 — one-time browser flow, no API keys
Available tools	11 tools covering projects, todos, tags, time entries, timers, and reporting

Connect from

• Claude Code
• Claude Desktop
• Cursor
• VS Code (GitHub Copilot)
• Windsurf
• ChatGPT
• Codex
• Other tools

Claude Code

Run this command in your terminal:

claude mcp add --transport http lucen-track https://track-api.lucensoftware.com/mcp

Then authenticate by running /mcp in Claude Code and following the OAuth flow.

For a richer experience, install the Lucen Track plugin for Claude Code. It bundles the MCP server with slash commands (/log-time, /track-timer, /fix-entry, /time-report) for common workflows.

Using --scope flags for different installation scopes

• --scope local (default): Available only to you in the current project
• --scope project: Shared with your team via .mcp.json
• --scope user: Available to you across all projects

Use /mcp to list and manage MCP servers, and /context to see token usage per server.

Claude Desktop

1. Open Settings → Connectors
2. Click Add Connector and enter the URL:
   https://track-api.lucensoftware.com/mcp
3. Complete the OAuth flow to connect your Lucen Track workspace

Note: Remote MCP servers in Claude Desktop are configured through Settings → Connectors, not the claude_desktop_config.json file. Available on Pro, Max, Team, and Enterprise plans.

Cursor

1. Open Cursor Settings → MCP → Add new global MCP server
2. Paste the following configuration:

{ "mcpServers": { "lucen-track": { "url": "https://track-api.lucensoftware.com/mcp" } } }

1. Save and restart Cursor. The first time you use a Lucen Track tool, complete the OAuth flow.

Project-level configuration

To share the Lucen Track MCP configuration with your team, create a .cursor/mcp.json file in your project root with the same server configuration shown above.

VS Code (GitHub Copilot)

1. Create a .vscode/mcp.json file in your workspace:

{
"servers": {
"lucen-track": {
"type": "http",
"url": "https://track-api.lucensoftware.com/mcp"
}
}
}

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run MCP: List Servers
2. Start the Lucen Track server and complete the OAuth flow when prompted

User-level configuration

To configure Lucen Track MCP across all workspaces, run MCP: Open User Configuration from the Command Palette and add the server there.

Windsurf

1. Open Windsurf Settings (Cmd+, on Mac) → search for MCP
2. Click View raw config to open mcp_config.json
3. Add the Lucen Track server configuration:

{ "mcpServers": { "lucen-track": { "serverUrl": "https://track-api.lucensoftware.com/mcp" } } }

1. Save and restart Windsurf. Complete the OAuth flow when prompted.

ChatGPT

1. Go to chatgpt.com/#settings/Connectors (requires login)
2. Click Add Connector and enter the URL:

https://track-api.lucensoftware.com/mcp

1. Complete the OAuth flow to connect your Lucen Track workspace

MCP connectors in ChatGPT require a Plus, Team, or Enterprise plan.

Codex

For more details, see the Codex MCP documentation.

1. Add the Lucen Track server to your Codex configuration at ~/.codex/config.toml:

[mcp_servers.lucen-track] url = "https://track-api.lucensoftware.com/mcp"

1. Authenticate by running:

codex mcp login lucen-track

1. Complete the OAuth flow to connect your Lucen Track workspace.

To share the Lucen Track MCP configuration with your team, create a .codex/config.toml file in your project root with the same server configuration.

Other tools

If your AI tool isn't listed above but supports MCP, you can connect using one of these:

Transport	URL	Notes
Streamable HTTP (recommended)	https://track-api.lucensoftware.com/mcp	Modern transport, widely supported

JSON configuration format

Most MCP clients accept a JSON configuration. Use the appropriate format for your tool:

Streamable HTTP

STDIO via mcp-remote

{ "mcpServers": { "lucen-track": { "command": "npx", "args": ["-y", "mcp-remote", "https://track-api.lucensoftware.com/mcp"] } } }

Use the STDIO configuration if your tool doesn't support remote HTTP connections directly. Requires Node.js installed on the local machine.

Troubleshooting

1) My tool doesn't support remote MCP servers

Some MCP clients only support local stdio servers. You can still connect to Lucen Track MCP using the mcp-remote bridge:

Requires Node.js installed on the local machine.

2) Authentication issues

• Make sure you complete the OAuth flow when prompted
• Try disconnecting and reconnecting — look for a "Clear authentication" or "Disconnect" option in your tool's MCP settings
• If you used mcp-remote, delete the cached token under ~/.mcp-auth/ and restart the client
• Verify you have the correct permissions in the Lucen Track workspace you're trying to access

3) The AI can't find my project or todo

The MCP server only sees data your authenticated user has visibility to in Lucen Track. If a project, todo, or tag doesn't appear:

• Confirm you're logged in to the correct Lucen Track account
• Check the project is active and you're a member
• For todos: ensure the integration ID (Jira/Asana reference) is exactly as it appears in the linked system

4) My tool isn't listed here

Check your tool's documentation for how to add a remote MCP server. Most tools accept either a URL directly or a JSON configuration. If your tool doesn't support MCP yet, consider reaching out to the developers to request MCP support.

FAQ

Can I use Lucen Track MCP without a human in the loop?

Lucen Track MCP requires user-based OAuth authentication and does not currently support bearer-token access. This means a user must complete the OAuth flow to authorize access, which may not be suitable for fully automated workflows or cloud-based agents that run without human interaction.

If you need headless or automated access, you can call the underlying Lucen Track REST API directly with an OAuth token, though MCP is the recommended path for AI-assistant use cases.

Is my time tracking data used to train AI?

Lucen Track never uses your tracked data to train AI models. The data sent to the AI tool you connect (Claude, ChatGPT, etc.) is governed by that tool's terms — for Claude, Anthropic's commercial terms exclude data passed through the Connectors Directory from model training.

What can the MCP server actually do?

The server exposes 11 tools covering reads (projects, todos, tags, entries, summaries, reports, active timer state) and writes (create / update time entries, start / stop timers). It does not expose administrative operations like creating projects, inviting users, or changing billing settings.

How do I disconnect?

From inside your AI tool's MCP / Connectors panel. Revoking the OAuth token immediately stops further data flow.

If you're integrating Lucen Track MCP into your own application or building a custom AI tool, see the MCP client documentation for step-by-step instructions on implementing OAuth and connecting to a remote MCP server. The Lucen Track endpoint follows the standard MCP OAuth discovery flow.