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](../scheduling/SKILL.md) - Booking technicians against PSA tickets