Skip to main content
Glama
WYRE-AI

timezest-mcp

by WYRE-AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

TimeZest MCP Server

Docker Image License

MCP (Model Context Protocol) server for TimeZest scheduling platform. Enables LLM agents to create and manage technician scheduling requests with PSA integration.

Features

  • 🎯 Decision-tree navigation - organized tool discovery

  • 📅 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_get renders as a card in MCP Apps hosts; neutral by default, brandable via window.__BRAND__ injection or MCP_BRAND_* env vars

Related MCP server: OnSched Consumer API MCP Server

Quick Start

Docker (Recommended)

docker run -it --rm \
  -e TIMEZEST_API_TOKEN=your-api-token \
  ghcr.io/wyre-ai/timezest-mcp:latest

npm

npm install -g @wyre-ai/timezest-mcp
TIMEZEST_API_TOKEN=your-token timezest-mcp

Configuration

Environment Variable

Required

Description

TIMEZEST_API_TOKEN

Yes

TimeZest API token

MCP_TRANSPORT

No

Transport mode: stdio (default) or http

MCP_HTTP_PORT

No

HTTP port (default: 8080)

AUTH_MODE

No

Set to gateway for WYRE gateway integration

LOG_LEVEL

No

Log level: debug, info (default), warn, error

Tool Domains

The server uses decision-tree navigation to organize tools by domain:

Navigation

  • timezest_navigate - Enter a domain to access its tools

  • timezest_status - Show available domains and current state

Agents

  • timezest_agents_list - List individual technicians

  • timezest_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 types

  • timezest_appointment_types_get - Get appointment type details

Resources

  • timezest_resources_list - List all resources (agents + teams)

Scheduling (Core Domain)

  • timezest_scheduling_list - List scheduling requests

  • timezest_scheduling_get - Get request details

  • timezest_scheduling_create_request - Create new request (key tool)

  • timezest_scheduling_cancel - Cancel request

Usage Examples

Basic Navigation

User: "Show me TimeZest domains"
Tools: timezest_status

User: "Go to scheduling"
Tools: timezest_navigate(domain="scheduling")

Create 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 dev

Docker Development

# Build image
docker build -t timezest-mcp --build-arg NODE_AUTH_TOKEN=$GITHUB_TOKEN .

# Run container
docker run -it --rm \
  -e TIMEZEST_API_TOKEN=your-token \
  -e LOG_LEVEL=debug \
  timezest-mcp

MCP 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)

  • Header-based credential injection

  • Structured error responses

  • Decision-tree tool organization

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

2 tools
timezest_navigateC

Navigate to a specific TimeZest domain to access its tools

ParametersJSON Schema
NameRequiredDescriptionDefault
domainYesDomain to navigate to

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden of disclosing behavioral traits. It states the action but does not mention side effects (e.g., whether the current domain is changed for subsequent calls), authentication requirements, or what the tool returns. This is minimal disclosure for a state-changing operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the essential purpose without redundancy. It is appropriately concise for a simple navigation tool with only one parameter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and the description does not explain what the tool returns or how navigation affects subsequent operations. For a tool that changes context, the lack of information about side effects and return value is a significant gap, even though parameters are well-documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully documents the domain parameter with an enum and a description, giving 100% schema coverage. The description adds no additional meaning about the parameter, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb 'navigate' and a resource 'TimeZest domain', distinguishing it from the sibling tool timezest_status which presumably checks status. However, 'to access its tools' is somewhat vague about the operational effect, so it doesn't fully meet the 5-level of specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is provided on when to use this tool versus alternatives. It does not mention timezest_status or any exclusion criteria. The only implicit usage is derived from the purpose, which is not enough to guide an agent in tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

timezest_statusA

Show current navigation state and available domains

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It clearly indicates a read-only operation ('Show') with no destructive hints. Though it lacks details like real-time freshness, the intent is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no waste. It is front-loaded with the action and content, and every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and no annotations, the description is adequate for a simple status tool. However, it could clarify what 'navigation state' and 'available domains' entail for better completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and per guidelines baseline is 4. The description does not need to add parameter info since none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Show') and the specific resources ('current navigation state and available domains'). It distinguishes itself from the sibling tool 'timezest_navigate' which implies navigation versus status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking status before navigating, but does not explicitly state when to use this tool versus the sibling 'timezest_navigate'. No exclusions or alternatives are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.2.6
    • Addedtimezest_navigate
  2. 1 tool updatev1.2.5
    • Removedtimezest_navigate
  3. 2 tool updatesv1.1.2
    • First observedtimezest_navigate
    • First observedtimezest_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one performs navigation to a domain, and the other reports the current navigation state and available domains. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tools follow the same naming pattern with the 'timezest_' prefix and lowercase snake_case. The style is consistent, even though one uses a verb and the other a noun.

Tool Count3/5

With only 2 tools, the server feels thin and borderline for the stated purpose of navigating domains. The count is not excessive, but it is below the typical well-scoped range of 3-15 tools.

Completeness4/5

The pair covers the core operations of navigating to a domain and checking status/available domains. Minor gaps might exist, such as a way to navigate back or list domains explicitly, but the current surface is functional for basic usage.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers