Connect Homebase to Claude: Sync Timecards and Monitor Shift Data

If your team needs to connect Homebase to Claude to automate timecard reconciliation, monitor shift coverage, or audit labor costs, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and Homebase's REST API. You can either build and maintain this infrastructure in-house, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Homebase to ChatGPT or explore our broader architectural overview on connecting Homebase to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling workforce management system like Homebase is a serious engineering challenge. You have to handle OAuth 2.0 token lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with strict pagination limits. Every time Homebase updates an endpoint or changes a labor calculation, 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 Homebase, connect it natively to Claude, and execute complex labor management workflows using natural language.

The Engineering Reality of the Homebase 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. Homebase is built to manage hourly workforces, locations, complex labor compliance, and payroll exports. Its API reflects that complexity.

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

The Time-Off Labor Calculation Quirk One of the most dangerous traps in the Homebase API is how it handles time-off calculations on individual timecards. If you query the timecards resource directly, the time-off labor totals (Paid Time Off, Sick Time, Unpaid Time Off, and FFCRA fields) are explicitly hardcoded to zero. If you expose only the timecards endpoint to an LLM for payroll reconciliation, the agent will confidently hallucinate incorrect payroll totals for any employee who took time off. To get accurate aggregates that include time off, you must force the LLM to use the separate labor_by_employee resource. A managed MCP server helps you inject instructions into the tool descriptions so the model knows exactly which endpoint to trust for financial data.

Link Header Pagination and Cursor Injection Homebase relies heavily on HTTP Link headers for pagination rather than simple offset/limit JSON bodies. The API sets page sizes via a per_page parameter, but Truto normalizes this standard to a universal limit parameter for the LLM. More importantly, when building an MCP tool, you must explicitly instruct the LLM on how to handle the next_cursor. If the LLM tries to decode, modify, or parse the cursor string before passing it back, the pagination will fail. Truto dynamically injects strict schema definitions instructing the LLM to pass cursor values back unchanged.

State Synchronization via Deleted Records Workforce schedules change constantly. Shifts get dropped, swapped, or deleted. If you are syncing Homebase data to a data warehouse or triggering external events based on shift data, you cannot just query the active shifts endpoint. Homebase provides specific endpoints like deleted_shifts and deleted_timecards that require a location_uuid, start_date, and end_date. Exposing these to an LLM requires carefully mapping query parameters so the model can cross-reference active vs. deleted records to maintain accurate state.

How to Generate a Homebase MCP Server

Truto derives MCP tools dynamically from the integration's resource configurations and documentation schemas. Instead of writing custom JSON-RPC handlers for every Homebase endpoint, Truto generates them on the fly. You can spin up an MCP server for Homebase using either the Truto UI or the API.

Method 1: Via the Truto UI

For administrators and operators, the UI provides the fastest path to a working MCP server.

1. Log into your Truto dashboard and navigate to your Integrated Accounts.
2. Select your connected Homebase account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (name, allowed methods, tags, expiry).
6. Click Save and copy the generated MCP server URL.

Method 2: Via the Truto API

For developers building programmatic agent onboarding, you can generate MCP servers via a simple POST request. Truto will validate that the integration is AI-ready, generate a secure random hex string, hash it, and store it in distributed edge KV storage for low-latency token validation.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homebase Labor Agent",
    "config": {
      "methods": ["read", "write"]
    }
  }'

The response will return a fully authenticated JSON-RPC 2.0 endpoint:

{
  "id": "abc-123",
  "name": "Homebase Labor Agent",
  "config": { "methods": ["read", "write"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

This URL contains a cryptographic token that securely identifies the connected Homebase tenant.

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude environment.

Method 1: Via the Claude UI

If you are using Claude's web interface or team workspaces:

1. In Claude, navigate to Settings → Integrations → Add MCP Server.
2. Give the connector a name (e.g., "Homebase Production").
3. Paste the Truto MCP Server URL.
4. Click Add.

Claude will immediately call the /initialize protocol method, handshake with the Truto router, and list the available Homebase tools.

Method 2: Via the Claude Desktop Config File

If you are running Claude Desktop locally or configuring an agentic framework, you can inject the server via the claude_desktop_config.json file. Because Truto uses Server-Sent Events (SSE) for remote MCP, you will use the official MCP SSE transport utility.

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

Restart Claude Desktop. The Homebase tools will now appear under the plug icon in your chat interface.

Security and Access Control

Giving an LLM direct access to payroll and scheduling data requires strict governance. Truto's MCP architecture enforces security at the token level, ensuring the LLM can only execute what you explicitly permit.

• Method Filtering (config.methods): Restrict the MCP server to specific operation types. Pass ["read"] to allow only get and list operations, preventing the LLM from accidentally updating a timecard or deleting a shift.
• Tag Filtering (config.tags): Group tools by business function. If you only want the LLM analyzing labor costs, you can filter by ["labor", "reporting"] to exclude unrelated endpoints like messaging or applicant tracking.
• Expiration Dates (expires_at): Generate ephemeral MCP URLs that automatically self-destruct. Truto schedules a cleanup alarm that wipes the token from both the database and edge KV storage once the ISO datetime passes.
• Extra Authentication (require_api_token_auth): For highly sensitive environments, toggle this flag to true. The caller will be forced to pass a valid Truto API token in the Authorization header, adding a second layer of identity verification beyond possessing the URL.

Homebase Hero Tools for Claude

Truto automatically translates Homebase endpoints into strictly typed MCP tools. Below are the highest-leverage operations for workforce and labor management.

list_all_homebase_locations

Homebase operations are strictly partitioned by location. Almost every other endpoint (shifts, employees, timecards) requires a location_uuid. This tool is the necessary first step in any agent workflow, allowing the LLM to discover the correct identifier for a given branch or store.

"Fetch all active locations for our account and tell me the location_uuid for the 'Downtown Seattle' store."

list_all_homebase_employees

Retrieves the workforce roster for a specific location. Truto handles the Link header pagination behind the scenes. This is critical for mapping an employee's natural language name to their internal Homebase id or job_id.

"List all employees for the Downtown Seattle location and give me the internal IDs for the shift supervisors."

list_all_homebase_shifts

Queries the active schedule for a location within a specific date range. This allows the LLM to audit coverage, identify overtime risks, or prepare daily shift briefings.

"Pull the shifts for location_uuid 'loc-123' for next week (Monday to Friday). Are there any days where we have fewer than three cashiers scheduled?"

list_all_homebase_timecards

Retrieves standard timecard records. Remember the API quirk: this endpoint does not accurately reflect time-off labor totals. It is best used for auditing standard punch-in and punch-out times, finding missed breaks, or tracking actual vs. scheduled hours for standard worked shifts.

"Fetch the timecards for yesterday at the Downtown Seattle location. Did anyone clock in more than 15 minutes late?"

list_all_homebase_labor_by_employee

This is the source of truth for payroll calculation. It returns aggregated labor totals for a specific location and date range, correctly factoring in Paid Time Off, Sick Time, and FFCRA data.

"Get the total labor by employee for the first two weeks of this month. Flag anyone who exceeded 40 hours of combined regular and PTO hours."

list_all_homebase_deleted_shifts

Retrieves the IDs of shifts that were deleted within a given timeframe. This is a critical state-management tool for AI agents responsible for keeping external systems (like a shared Google Calendar or external shift-bidding app) in sync with Homebase.

"Check for any deleted shifts over the last 24 hours for the Seattle location, and cross-reference them with the active schedule to tell me who got their hours cut."

For the complete inventory of available Homebase tools, schema definitions, and custom endpoints, visit the Truto Homebase Integration Page.

Workflows in Action

With the MCP server connected to Claude, you can orchestrate complex, multi-step workforce operations using natural language.

Scenario 1: Payroll Reconciliation and Overtime Audit

An operations manager wants to verify weekly labor totals before exporting data to their payroll provider, ensuring no one triggered unapproved overtime while factoring in PTO.

Prompt: "Audit our labor hours for the 'Brooklyn Cafe' location for the previous work week. Check if anyone exceeded 40 total hours (including time off). If they did, cross-reference their daily timecards to see if they missed their mandatory 30-minute unpaid breaks."

1. list_all_homebase_locations: Claude fetches the account locations and extracts the location_uuid for "Brooklyn Cafe".
2. list_all_homebase_labor_by_employee: Claude queries the true labor aggregates (which include PTO and sick time) for the date range.
3. Data Analysis: The model identifies two employees who exceeded 40 hours.
4. list_all_homebase_timecards: Claude queries the daily timecards specifically for those two employees to analyze their punch-in, punch-out, and break data.
5. Response: Claude provides a written report confirming the overtime and noting whether the employees took their legally required meal breaks.

flowchart TD
  A["Claude Agent"] -->|"Call: list_all_homebase_locations"| B["Truto MCP Server"]
  B --> C["Extract location_uuid<br>for Brooklyn Cafe"]
  A -->|"Call: list_all_homebase_labor_by_employee<br>(start_date, end_date)"| B
  B --> D["Identify employees<br>> 40 total hours"]
  A -->|"Call: list_all_homebase_timecards<br>(Filtered by employee)"| B
  B --> E["Audit daily punches<br>and break compliance"]

Scenario 2: Shift Deletion Sync and Coverage Alerting

A store manager wants a morning briefing on schedule changes that happened overnight so they can find emergency coverage.

Prompt: "Check the 'Downtown Retail' location for any shifts deleted in the last 12 hours. Tell me which roles are now understaffed for today's active schedule based on those deletions."

1. list_all_homebase_locations: Claude retrieves the location_uuid for "Downtown Retail".
2. list_all_homebase_deleted_shifts: Claude fetches the IDs of all shifts wiped from the system overnight.
3. list_all_homebase_shifts: Claude pulls the active schedule for the current day to see the surviving coverage.
4. list_all_homebase_employees: Claude maps the employee and job IDs from the shift data to actual job titles (e.g., "Keyholder", "Cashier").
5. Response: Claude informs the manager: "Two Cashier shifts were deleted last night. You only have one active Cashier scheduled from 2 PM to 6 PM today, leaving you understaffed."

Handling Rate Limits in Production

When deploying AI agents in production, you must account for API rate limits. Homebase enforces strict quotas on how frequently you can query their endpoints.

Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Homebase API returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller (your MCP client or agent framework).

However, Truto normalizes the upstream rate limit information into standardized headers per the IETF specification:

• ratelimit-limit: The total requests allowed in the current window.
• ratelimit-remaining: The number of requests left.
• ratelimit-reset: The timestamp when the quota refreshes.

The caller (your AI agent's infrastructure) is entirely responsible for reading these headers and implementing its own retry logic or exponential backoff.

Connecting Your Tech Stack

Connecting Claude to Homebase via a managed MCP server removes the heavy lifting of OAuth lifecycles, schema mapping, and pagination logic. By turning Homebase's complex REST APIs into standardized, self-describing tools, your AI agents can safely audit payroll, monitor shift coverage, and reconcile deleted records in real-time.