Connect Hourtick to Claude: Sync Reports and Collaborate in Chat

If your team needs to connect Hourtick to Claude to automate time tracking, extract project profitability reports, or collaborate directly within team chat channels, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM function calls and Hourtick's REST APIs. You can either build and maintain this integration infrastructure yourself, or use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Hourtick to ChatGPT or explore our broader architectural overview on connecting Hourtick to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling workspace management ecosystem like Hourtick presents serious engineering friction. You have to handle OAuth 2.0 token lifecycles, map complex JSON schemas to MCP tool definitions, and deal with Hourtick's specific architectural quirks. Every time Hourtick updates an endpoint or alters a schema, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Hourtick, connect it natively to Claude Desktop, and execute complex workflows using natural language.

The Engineering Reality of the Hourtick API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized B2B APIs is painful. Hourtick is built to handle highly mutable states - running timers, complex timesheet approvals, chat streams, and even AI agent cost ledgers. Its API reflects that complexity.

If you decide to build a custom Hourtick MCP server, here are the specific integration challenges you will face:

CQRS and Idempotent Command Patterns

Unlike typical REST APIs where you issue a standard POST or PATCH to update a record, Hourtick handles time entries via an idempotent command pattern. Starting, stopping, editing, or restoring a timer requires calling create_a_hourtick_command. This endpoint requires an expectedVersion for edits and an idempotent commandId to ensure retries do not duplicate time entries. An LLM cannot naturally guess this architecture. Your MCP server must expose strictly defined tool schemas that force Claude to fetch the current version of an entry before attempting to mutate it.

Untyped JSON Responses and Opaque Objects

Several critical Hourtick endpoints - such as fetching chat searches, timesheet actions, or complex agent activity logs - do not have strictly enumerated fields in the upstream API specification. They return untyped JSON objects. If you are building a custom integration layer, you have to write custom deserialization logic to handle these varying payloads. Truto handles this by passing the raw, un-opinionated proxy API response directly back to the LLM, allowing Claude's inherent parsing capabilities to extract the relevant data dynamically.

Rate Limiting and Backoff Management

LLMs are aggressive. When asked to summarize a month of activity, Claude might try to sequentially loop through dozens of paginated endpoints, hitting Hourtick's rate limits rapidly. Truto does not retry, throttle, or absorb rate limit errors. Instead, when Hourtick returns an HTTP 429, Truto passes that error directly back to the caller while normalizing the upstream rate limit data into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). This means your MCP client implementation must be responsible for catching the 429, reading the reset header, and instructing the LLM to pause before retrying.

Generating the Hourtick MCP Server

Truto dynamically derives MCP tools from Hourtick's API documentation and endpoint definitions. Tools are never cached or pre-built; they are generated on the fly when Claude requests the /tools/list endpoint.

You can generate the MCP server URL using either the Truto UI or the Truto API.

Method 1: Via the Truto UI

For teams who want a zero-code setup:

1. Log into your Truto dashboard and navigate to the integrated account page for your specific Hourtick connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure your server. You can select specific method filters (e.g., restricting the server to read operations only) or filter tools by specific tags.
5. Click Save and copy the generated MCP server URL. It will look like this: https://api.truto.one/mcp/a1b2c3d4...

Method 2: Via the Truto API

For platform engineers dynamically provisioning servers for their end-users, you can call the Truto API. This is the exact underlying mechanism the UI uses.

Make a POST request to /integrated-account/:id/mcp with your desired configuration:

curl -X POST "https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourtick Read-Only Agent",
    "config": {
      "methods": ["read", "list"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions the secure routing and returns a response containing the self-contained tokenized URL:

{
  "id": "mcp-789",
  "name": "Hourtick Read-Only Agent",
  "config": { "methods": ["read", "list"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting Hourtick to Claude

Once you have the Truto MCP URL, you need to connect it to your Claude client. The URL itself encodes the authentication token, the integrated account context, and any method or tag filters you applied.

Method A: Via the Claude UI

If you are using Claude's web interface or enterprise team settings that support UI-based connector management:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server.
2. Give the integration a descriptive name (e.g., "Hourtick Production Data").
3. Paste the URL provided by Truto.
4. Click Add. Claude will immediately handshake with the server, hit the tools/list endpoint, and ingest the available Hourtick tools.

Method B: Via Manual Config File

If you are using Claude Desktop or building a custom LangChain/LangGraph agent, you can mount the server via the configuration file. Truto's MCP servers communicate over HTTP using Server-Sent Events (SSE).

Locate your claude_desktop_config.json file and append the Truto server configuration:

{
  "mcpServers": {
    "hourtick_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

Restart Claude Desktop. The application will initialize the connection and map the Hourtick APIs as callable tools.

Essential Hourtick MCP Tools for Claude

Truto provides a comprehensive mapping of Hourtick's endpoints. Here are the highest-leverage hero tools to expose to Claude for workflow automation.

create_a_hourtick_command

This is the core tool for mutating time entry state. It allows Claude to start, stop, edit, or restore time entries safely using Hourtick's idempotent command structure. Claude must pass a unique commandId alongside the intended state change.

"I just finished my meeting with the Acme Corp team. Stop my current running timer, log the duration, and add the note 'Quarterly review presentation'."

list_all_hourtick_time_entries

Allows the LLM to pull historical time logs or check the status of a currently running timer. The query schema requires a date range (from and to) and returns highly detailed entry logs including billable status, project IDs, and duration.

"List all my time entries for this week. Separate out the billable hours from the internal non-billable tasks and give me a total sum for both."

list_all_hourtick_reports

Exposes Hourtick's reporting engine. Managers and admins can pull team scopes, grouping data by project or user, and even extracting P&L data (costs, profit, uncosted seconds) dynamically.

"Generate a project profitability report for the Q3 Website Redesign project. Break down the costs by team member and highlight any uncosted seconds."

list_all_hourtick_work_items

Allows Claude to interact with Hourtick's Kanban board representation of tasks. It retrieves tasks with their status, priority, labels, and assignee arrays, which is critical for agentic triage workflows.

"What are my open high-priority work items assigned to the 'DevOps' label? Summarize their current status."

create_a_hourtick_chat_message

Connects Claude directly into Hourtick's internal communication system. Claude can post updates to specific channels, and notably, mentioning an AI agent within the body payload will automatically queue a session for that agent.

"Post an update in the #engineering channel letting the team know that the staging deployment is complete. Mention the @QA-Agent to begin the regression test suite."

list_all_hourtick_agent_costs

Crucial for teams managing heavy AI workloads. This tool retrieves the agent cost ledger, allowing Claude to audit token usage (input/output) and exact USD costs associated with specific models and agents over a given period.

"Review the AI agent costs for last month. Which specific agent consumed the most budget, and what was the split between input and output tokens?"

To view the complete schema definitions and the full inventory of available endpoints, visit the Hourtick Integration Page.

Workflows in Action

Once the tools are mapped, Claude can chain them together to execute complex, multi-step operations. Here are two real-world workflows.

Workflow 1: End-of-Week Timesheet Reconciliation

Many engineering teams struggle with timesheet compliance. Instead of manually auditing logs, an IT admin can ask Claude to verify the week's tracked time and submit the timesheet if it looks correct.

"Review my time entries for the current week starting Monday. If I have logged more than 35 billable hours, go ahead and submit my timesheet for approval."

Execution Flow:

1. Claude calls list_all_hourtick_time_entries passing the current week's date bounds.
2. The model aggregates the durationSeconds array where billable is true, converting the sum to hours.
3. Upon verifying the condition (>35 hours), Claude executes create_a_hourtick_timesheet passing the weekStart date and the action parameter set to submit.

sequenceDiagram
    participant User
    participant Claude
    participant Truto
    participant Hourtick as Hourtick API
    
    User->>Claude: "Review time and submit timesheet"
    Claude->>Truto: Call list_all_hourtick_time_entries<br>(from: Mon, to: Fri)
    Truto->>Hourtick: GET /time-entries
    Hourtick-->>Truto: Return JSON array of entries
    Truto-->>Claude: Forward entries data
    Claude->>Claude: Calculate billable hours
    Claude->>Truto: Call create_a_hourtick_timesheet<br>(action: submit)
    Truto->>Hourtick: POST /timesheets/submit
    Hourtick-->>Truto: Return 200 OK
    Truto-->>Claude: Confirm submission
    Claude-->>User: "Timesheet submitted successfully."

Workflow 2: Automated Chat Updates and Task Triage

Project managers can use Claude to audit board health and communicate delays automatically, entirely through natural language.

"Find any open work items on the 'Frontend Migration' project that are marked as high priority but haven't been updated this week. Post a warning message in the #frontend channel listing those tasks."

Execution Flow:

1. Claude triggers list_all_hourtick_work_items filtering for the specific project ID.
2. It filters the returned JSON array looking for objects where priority is high and the updated timestamp is older than 7 days.
3. Claude formats a readable summary of the stalled tasks.
4. It executes create_a_hourtick_chat_message, passing the channel_id for #frontend and the formatted markdown summary as the body.

flowchart TD
    A["User Prompt:<br>Find stalled tasks & update chat"] --> B["list_all_hourtick_work_items<br>(Query Kanban board)"]
    B --> C{"Are there stalled<br>high-priority tasks?"}
    C -->|Yes| D["Format markdown list"]
    D --> E["create_a_hourtick_chat_message<br>(Post to #frontend)"]
    C -->|No| F["Return: All tasks on track"]

Security and Access Control

Exposing B2B data to LLMs requires strict governance. Truto's MCP implementation provides several layers of access control, configured at the token level when you generate the server URL:

• Method Filtering: Limit Claude's capabilities to specific operations. Setting config: { methods: ["read"] } ensures the LLM can only execute get or list tools, preventing accidental data deletion or unauthorized time entries.
• Tag Filtering: Restrict access to specific domains within the integration. If you only want Claude handling support queries, you can restrict the server to tools tagged with chat or reports.
• Expiration Enforcement (TTL): Use the expires_at property to create temporary MCP servers. This is ideal for short-lived contract work or automated CI/CD runs. Once the ISO datetime is reached, the server is automatically destroyed via Truto's underlying durable object alarms.
• Require API Token Auth: By default, possessing the MCP URL grants access to the tools. By enabling require_api_token_auth, you force the calling client to also pass a valid Truto API token in the authorization header, adding a strict secondary identity check.

Ship Secure Integrations Faster

Connecting Hourtick to Claude via Truto removes the entire burden of managing authentication state, building error-handling wrappers, and maintaining custom tool schemas. Instead of wrestling with Hourtick's idempotent command structures and untyped JSON payloads in custom middleware, your engineering team can focus purely on agent logic and prompt orchestration.

By dynamically generating MCP servers directly from documentation, Truto ensures your AI agents always have access to the latest APIs, governed by strict method and tag controls.