timezest-mcp
This server is an MCP interface to TimeZest for creating and managing technician scheduling requests with PSA integration.
Check status:
timezest_statusshows connection status and available tools.Manage agents: list and get individual technician details.
Manage teams: list and get team/round-robin scheduling details.
Browse appointment types: list and get service/appointment type details.
View resources: list combined agents and teams, optionally filtered by type.
Handle scheduling requests: list, get details, create new bookings, and cancel requests.
Create bookings with end-user info, preferred time windows (IANA timezone), specific resources, appointment type, notes, and trigger mode.
Integrate with PSA systems: associate requests with ConnectWise, Autotask, or Halo tickets.
Generate booking URLs: use
triggerMode: generate_urlto return a shareable customer booking link, orpodto fire PSA workflow.Filter data with TQL: use TimeZest Query Language filters on list endpoints and by status/resource type where supported.
Interactive card rendering: scheduling request details can render as a card in MCP Apps hosts.
TimeZest MCP Server
MCP (Model Context Protocol) server for TimeZest scheduling platform. Enables LLM agents to create and manage technician scheduling requests with PSA integration.
Features
🎯 Flat tool list - every tool listed and callable immediately
📅 Full scheduling lifecycle - create, view, cancel requests
🔗 PSA integration - ConnectWise, Autotask, Halo support
🌍 IANA timezone handling - explicit timezone management
🚀 Dual trigger modes - PSA workflows or booking URLs
🛡️ Gateway-ready - stateless per-request design
🔍 TQL filtering - TimeZest Query Language support
✨ Elicitation support - interactive user prompts
📇 Interactive scheduling-request card (MCP Apps) -
timezest_scheduling_getrenders as a card in MCP Apps hosts; neutral by default, brandable viawindow.__BRAND__injection orMCP_BRAND_*env vars
Related MCP server: TimePRO MCP Server
Quick Start
Docker (Recommended)
docker run -it --rm \
-e TIMEZEST_API_TOKEN=your-api-token \
ghcr.io/wyre-ai/timezest-mcp:latestnpm
npm install -g @wyre-ai/timezest-mcp
TIMEZEST_API_TOKEN=your-token timezest-mcpConfiguration
Copy .env.example and set the variables below.
Environment Variable | Required | Description |
| For stdio and | TimeZest API token. Gateway mode does not read this. |
| No |
|
| No | HTTP port. Defaults to |
| No | Bind address when |
| No |
|
| Yes for HTTP | Service-to-service secret. Generate one with |
| No | Set to exactly |
| No | Log level: |
/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The header value is:
t=<unix seconds>,v1=<hex hmac-sha256>v1 is HMAC-SHA256, as lowercase hex, of the exact ASCII string t=<unix seconds> (the same prefix that appears in the header), keyed with CONDUIT_S2S_SECRET. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401. The secret is never written to logs.
t=$(date +%s)
sig=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
# X-Gateway-S2S: t=$t,v1=$sigIn AUTH_MODE=gateway, /mcp also requires X-Timezest-Api-Token. That header is the only credential source for the request. A missing header returns 401 and the server does not fall back to TIMEZEST_API_TOKEN.
Tools
Every tool below is listed and callable immediately — there is no domain to enter first. The groupings are documentation only.
Upgrading from 2.x?
timezest_navigateandtimezest_backare gone. Nothing replaces them: call the domain tools directly, because they are all listed up front now. A client that used to calltimezest_navigate({domain: "agents"})and thentimezest_agents_listshould just calltimezest_agents_list— likewisetimezest_scheduling_listand the rest.timezest_statusstill works and now reports the available tools instead of a menu to enter.
Status
timezest_status- Show connection status and the available tools
Agents
timezest_agents_list- List individual technicianstimezest_agents_get- Get agent details
Teams
timezest_teams_list- List teams (round-robin scheduling)timezest_teams_get- Get team details
Appointment Types
timezest_appointment_types_list- List available service typestimezest_appointment_types_get- Get appointment type details
Resources
timezest_resources_list- List all resources (agents + teams)
Scheduling (Core Domain)
timezest_scheduling_list- List scheduling requeststimezest_scheduling_get- Get request detailstimezest_scheduling_create_request- Create new request (key tool)timezest_scheduling_cancel- Cancel request
Usage Examples
Check What's Available
User: "What can TimeZest do?"
Tools: timezest_statusCreate a Scheduling Request
User: "Book a technician for server repair at Customer Corp tomorrow"
Tools: timezest_scheduling_create_request({
"appointmentTypeId": "repair-onsite",
"triggerMode": "pod",
"endUser": {
"name": "John Doe",
"company": "Customer Corp",
"email": "john@customer.com"
},
"timeRange": {
"earliestDate": "2024-02-01",
"earliestTime": "09:00",
"latestDate": "2024-02-01",
"latestTime": "17:00",
"timezone": "America/New_York"
},
"associatedEntities": [
{"type": "connectwise", "id": "12345", "number": "T20240001"}
]
})PSA Integration
Link scheduling requests to PSA tickets:
{
"associatedEntities": [
{"type": "connectwise", "id": "12345", "number": "T20240001"},
{"type": "autotask", "id": "67890"},
{"type": "halo", "id": "11111"}
]
}Trigger Modes
pod: Fires the configured PSA workflow (creates calendar entries, updates tickets)generate_url: Returns a shareable booking URL for customers
TQL Filtering
TimeZest Query Language examples:
# Active agents in IT department
filter: "active:true AND department:\"IT Support\""
# Recent scheduling requests
filter: "createdAt:>=2024-01-01 AND status:pending"
# Specific customer requests
filter: "endUser.company:\"Important Customer\""Timezone Handling
CRITICAL: Always specify IANA timezones explicitly. TimeZest interprets scheduling windows in the specified timezone.
{
"timeRange": {
"earliestDate": "2024-02-01",
"earliestTime": "09:00",
"timezone": "America/New_York" // ✅ Required
}
}Development
Local Setup
# Clone and install
git clone https://github.com/WYRE-AI/timezest-mcp.git
cd timezest-mcp
npm install
# Development with file dependency (replace before publish)
# Edit package.json: "@wyre-technology/node-timezest": "file:../node-timezest"
# Build and test
npm run build
npm test
# Run locally
TIMEZEST_API_TOKEN=your-token npm run devDocker Development
The image sets AUTH_MODE=gateway and MCP_HTTP_HOST=0.0.0.0. Stdio (the image default until MCP_TRANSPORT=http) still reads TIMEZEST_API_TOKEN and does not use CONDUIT_S2S_SECRET.
# Build image
docker build -t timezest-mcp --build-arg NODE_AUTH_TOKEN=$GITHUB_TOKEN .
# Stdio
docker run -it --rm \
-e TIMEZEST_API_TOKEN=your-token \
-e LOG_LEVEL=debug \
timezest-mcpHTTP gateway mode publishes the port on loopback and passes the S2S secret. The TimeZest token arrives on each request as X-Timezest-Api-Token; it is not read from the environment. Generate the secret with openssl rand -hex 32 — example placeholders such as changeme or your-s2s-secret are rejected.
export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
docker run --rm \
-e MCP_TRANSPORT=http \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-p 127.0.0.1:8080:8080 \
timezest-mcpCompose refuses to start when CONDUIT_S2S_SECRET is unset. The gateway service sets AUTH_MODE=gateway and does not inject TIMEZEST_API_TOKEN or env_file:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses TIMEZEST_API_TOKEN:
docker run --rm \
-e MCP_TRANSPORT=http \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-e AUTH_MODE=env \
-e TIMEZEST_API_TOKEN=your-token \
-p 127.0.0.1:8080:8080 \
timezest-mcpLocal HTTP without a secret is development-only. It binds 127.0.0.1 only and logs a warning. A non-loopback MCP_HTTP_HOST is overridden:
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run devMCP Integration
Claude Desktop
Add to your MCP settings:
{
"mcpServers": {
"timezest": {
"command": "npx",
"args": ["@wyre-ai/timezest-mcp"],
"env": {
"TIMEZEST_API_TOKEN": "your-api-token"
}
}
}
}WYRE Gateway
The server is designed for the WYRE MCP Gateway with:
Per-request server instances (stateless)
X-Gateway-S2Ssigning on every/mcprequest (see HTTP authentication)X-Timezest-Api-Tokencredential injection in gateway mode, with no fallback toTIMEZEST_API_TOKENStructured error responses
Flat tool list (no navigation state to enter)
API Coverage
TimeZest API | Coverage | Notes |
Agents | ✅ List, Get | Individual technicians |
Teams | ✅ List, Get | Round-robin scheduling |
Appointment Types | ✅ List, Get | Service type definitions |
Resources | ✅ List | Unified agents + teams |
Scheduling Requests | ✅ CRUD | Core scheduling functionality |
TQL Filtering | ✅ All endpoints | TimeZest Query Language |
PSA Integration | ✅ All systems | ConnectWise, Autotask, Halo |
Webhooks | ❌ N/A | TimeZest doesn't provide webhooks |
Contributing
See CONTRIBUTING.md for development guidelines.
License
Apache 2.0 - see LICENSE file for details.
Links
Available Tools
12 toolstimezest_agents_getA
Get details for a specific agent by ID
Inputs: agentId (required).
timezest_agents_listB
List all agents (technicians) available for scheduling
Inputs: filter, pageSize.
timezest_appointment_types_getB
Get details for a specific appointment type by ID
Inputs: appointmentTypeId (required).
timezest_appointment_types_listB
List all appointment types available for scheduling
Inputs: filter, pageSize.
timezest_resources_listC
List all resources (agents and teams) available for scheduling
Inputs: type, filter, pageSize.
timezest_scheduling_cancelC
Cancel a scheduling request
Inputs: requestId (required), reason.
timezest_scheduling_create_requestC
Create a new scheduling request - supports PSA ticket association
Inputs: endUser (required), triggerMode (required), notes, timeRange, +3 more.
timezest_scheduling_getA
Get details for a specific scheduling request by ID
Inputs: requestId (required).
timezest_scheduling_listC
List scheduling requests
Inputs: filter, status, pageSize.
timezest_statusA
Show TimeZest connection status and the available tools
Inputs: no named parameters.
timezest_teams_getA
Get details for a specific team by ID
Inputs: teamId (required).
timezest_teams_listB
List teams available for scheduling. Deleted teams are omitted, using the same live set as timezest_resources_list (teams GET /v1/resources still returns).
Inputs: filter, pageSize.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action, with list/get pairs for agents, teams, appointment types, and scheduling requests. The main overlap is timezest_resources_list versus timezest_agents_list/timezest_teams_list, but the descriptions clarify that resources is the combined view.
Most tools follow the consistent pattern timezest_<resource>_<action>, using snake_case throughout. Minor inconsistencies exist, such as timezest_scheduling_create_request using a compound action while timezest_scheduling_cancel drops the '_request' suffix.
The 12 tools are well-scoped for a scheduling/fieldservice MCP server. Each tool covers a meaningful function without unnecessary duplication or bloat.
The tool set covers the core workflow: viewing status, reference data (agents, teams, resources, appointment types), listing/getting scheduling requests, and creating/canceling them. Minor gaps exist, such as no update/reschedule operation or agent availability check, but the main scheduling lifecycle is represented.
Maintenance
Related MCP Connectors
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
AI-native scheduling: check availability, book meetings, cancel and reschedule via MCP
Spacebring MCP server. Look up members, bookings, invoices, subscriptions, events and more, and take everyday actions such as creating events or replying to support tickets, from MCP-compatible AI assistants that support remote servers with OAuth.
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with OnSched's consumer-facing appointment scheduling API through natural language, allowing users to manage bookings, appointments, and scheduling operations.-
- AlicenseAqualityDmaintenanceAn MCP server that wraps the TimePRO API, enabling AI assistants to automatically create, view, and manage timesheets for authenticated users. It provides tools for searching clients and projects, retrieving configuration defaults, and performing full CRUD operations on timesheet entries.10MIT
- AlicenseAqualityDmaintenanceMCP server that connects AI agents to calendars, bookings, and scheduling polls via the Model Context Protocol.2210 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server that exposes the Orita scheduling API as tools for AI agents, enabling them to look up event types, book appointments, and manage bookings.36 PyPIMIT