TimeZest API Patterns

TimeZest MCP Tools & API Patterns

Overview

TimeZest provides scheduling-request flows tightly coupled to MSP PSA systems. A scheduling request is created against a PSA ticket (ConnectWise / Autotask / Halo), TimeZest sends the customer a self-service booking link, and the technician's calendar is updated when the customer picks a slot.

Connection & Authentication

TimeZest uses an API token passed via header.

Header	Value
X-Timezest-Api-Token	The raw TimeZest API token

The gateway maps the environment variable TIMEZEST_API_TOKEN onto the X-Timezest-Api-Token header automatically. Internally, the TimeZest MCP server forwards this to TimeZest as a Bearer token — you do not need to add the Bearer prefix yourself.

export TIMEZEST_API_TOKEN="your-timezest-token"

Navigation Tools

Tool	Purpose
timezest_navigate	Discover the available domains
timezest_back	Pop back to the prior context
timezest_status	Health/status check

Functional Tool Surface

Tools follow timezest_<domain>_<action>. Domains:

• agents (technicians)
• teams
• appointment_types
• resources
• scheduling (the primary domain)

Scheduling Request Payload — associated_entities

This is the most important pattern. When you call timezest_scheduling_create_request, the payload carries an associated_entities array that links the booking to a PSA record:

{
  "associated_entities": [
    {
      "type": "ConnectWiseTicket",
      "id": 12345
    }
  ]
}

Supported PSA types: ConnectWise tickets, Autotask tickets, Halo tickets. Always include the PSA association so the tech's PSA shows the booking.

Polling, Not Webhooks

TimeZest's MCP surface is poll-only. To track a booking's lifecycle (sent / clicked / booked / canceled), call timezest_scheduling_get on a cadence. Reasonable cadence:

• Every 1-2 minutes for "active" requests in the first hour.
• Every 10-15 minutes for the rest of the day.
• Stop polling once the request is in a terminal state.

Do not assume a webhook will arrive — none does at the MCP layer.

Error Handling

Status	Meaning	Action
401	Bad/missing Bearer token	Re-check TIMEZEST_API_TOKEN
403	Token valid but not authorized for the agent/team	Check token scope
404	Unknown agent / team / scheduling request	Re-list to confirm
422	Bad payload (missing PSA association, invalid appointment_type)	Validate input

Best Practices

• Always pass a PSA associated_entities entry — a booking with no PSA association is hard to find later.
• Resolve the agent and appointment_type via list calls before creating a request; do not hard-code IDs.
• For "book against this ticket" workflows, accept the PSA ticket ID as the primary input and resolve agent/team/appointment from context.

Related Skills

• scheduling - Booking technicians against PSA tickets