Model Context Protocol (MCP) Support
This feature is currently in preview and available for testing in the sandbox environment.
Integration with the Model Context Protocol (MCP), making Dime.Scheduler features accessible via this emerging protocol. This enables new ways to interact with Dime.Scheduler capabilities.
Supported Tools
The MCP integration provides the following tools organized by category. Each tool includes a description, parameters, and example usage.
Task Management
Get Open Tasks
Tool: get_open_tasks
Gets the unplanned (open) tasks that must yet be planned by the dispatcher.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Maximum number of results to return (default: 100) |
Example:
"What are the open tasks?"
Search Tasks
Tool: search_tasks
Searches for tasks by task number, subject, job, or other criteria. Returns matching tasks with their details.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
taskNo | string | No | Task number to search for (exact match) |
jobNo | string | No | Job number to filter by |
searchTerm | string | No | Search term to match against task subject or description |
categoryName | string | No | Category name to filter by |
limit | number | No | Maximum number of results to return (default: 100) |
Example:
"Search for tasks related to plumbing"
Job Management
Search Jobs
Tool: search_jobs
Searches for jobs by job number, name, or other criteria. Returns matching jobs with their details.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
jobNo | string | No | Job number to search for (exact match) |
searchTerm | string | No | Search term to match against job name or description |
categoryName | string | No | Category name to filter by |
limit | number | No | Maximum number of results to return (default: 100) |
Example:
"Find all jobs for project ABC123"
Resource Management
List Resources
Tool: list_resources
Lists all resources in the system with basic information.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
displayNameFilter | string | No | Filter by resource display name (partial match) |
Example:
"List all resources"
Get Resource Details
Tool: get_resource_details
Gets detailed information about a specific resource including skills, capacity, and calendar information.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
resourceDisplayName | string | Yes | The display name of the resource |
capacityStartDate | string | No | Start date for capacity and calendar information (ISO 8601 format, e.g., 2024-01-01T00:00:00Z) |
capacityEndDate | string | No | End date for capacity and calendar information (ISO 8601 format, e.g., 2024-01-31T23:59:59Z) |
Example:
"Get details for resource John Smith"
Get Resource Availability
Tool: get_resource_availability
Gets all availability periods (both available and unavailable time blocks) for a specific known resource during a time range. Returns raw availability periods without filtering by duration - periods can be any length. Use this ONLY when you need to see the complete raw availability timeline for debugging or calendar visualization purposes.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
resourceDisplayName | string | Yes | The display name of the resource |
startDateTime | string | Yes | The start date and time for the availability period (ISO 8601 format, e.g., 2024-01-01T00:00:00Z) |
endDateTime | string | Yes | The end date and time for the availability period (ISO 8601 format, e.g., 2024-01-31T23:59:59Z) |
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
Example:
"Show me all availability periods for John Smith next week"
Find Available Slots
Tool: find_available_slots
Finds all available time slots of a specified duration throughout a date range for a specific known resource. Returns only slots that exactly match the requested duration. This is the PREFERRED tool for finding available meeting times for a specific duration.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
resourceDisplayName | string | Yes | The display name of the resource |
startDate | string | Yes | The start date of the range to search for available slots (ISO 8601 format, e.g., 2024-01-09T00:00:00Z) |
durationInMinutes | number | Yes | The duration of the meeting in minutes (e.g., 30 for a 30-minute meeting, 60 for a 1-hour meeting) |
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
endDate | string | No | The end date of the range to search for available slots (defaults to the same day as startDate) |
Example:
"When is John Smith available for a 2-hour meeting this week?"
Check Time Slot Availability
Tool: check_time_slot_availability
Validates whether a specific time slot (start and end time) is available for a specific known resource. Returns a boolean answer (available/not available) plus any conflicting periods if unavailable.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
resourceDisplayName | string | Yes | The display name of the resource |
startDateTime | string | Yes | The start date and time of the time slot to check (ISO 8601 format, e.g., 2024-01-01T09:00:00Z) |
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
endDateTime | string | No | The end date and time of the time slot to check (defaults to 1 hour after start time) |
Example:
"Is John Smith available on January 15th at 2 PM?"
Get Recommendations
Tool: get_recommendations
DISCOVERY tool: Finds unknown resources matching skills/requirements and shows available slots. Use for finding resources that can do specific work. Do NOT use for reassigning existing appointments (use reschedule_appointment instead).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | Yes | The start date and time for the availability search window in UTC (ISO 8601 format, e.g., 2024-01-01T00:00:00Z) |
endDate | string | Yes | The end date and time for the availability search window in UTC (ISO 8601 format, e.g., 2024-01-31T23:59:59Z) |
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
requirements | string | No | Skills/abilities filter - what the resource CAN DO (e.g., 'plumbing', 'electrical work', 'HVAC', 'welding'). Can be comma-separated |
resourceTypes | string | No | Job role/description filter - what the resource IS (e.g., 'technician', 'engineer', 'driver', 'field worker'). Can be comma-separated |
duration | string | No | Required duration for the task in ISO 8601 format (e.g., PT2H for 2 hours, PT30M for 30 minutes) |
locationAddress | string | No | Location address string for proximity-based resource scoring |
locationCountry | string | No | Country code for geocoding (e.g., US, CA, GB) |
locationLatitude | number | No | Latitude for location (if address not provided) |
locationLongitude | number | No | Longitude for location (if address not provided) |
granularity | string | No | Time slot granularity in ISO 8601 format (e.g., PT15M, PT30M, PT1H) |
locationMode | string | No | Location mode: 'home' (default) or 'actual' (current GPS location) |
maxDistanceKm | number | No | Maximum distance in kilometers for resource filtering |
Example:
"Who is available this week for a 2-hour job nearby London (UK) with the skill electrician?"
Appointment Management
Get Resource Planning
Tool: get_resource_planning
Get planning or schedule for a specific resource. Fetches scheduled appointments (what is already planned/booked) for one or more specific known resources during a time range. Shows what appointments exist, their subjects, times, and assigned resources.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
resourceDisplayNames | string | Yes | The display names of the resources to fetch planning for (comma-separated) |
startDateTime | string | Yes | The start date and time for the planning period (ISO 8601 format, e.g., 2024-01-01T00:00:00Z) |
endDateTime | string | Yes | The end date and time for the planning period (ISO 8601 format, e.g., 2024-01-31T23:59:59Z) |
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
Example:
"Give me the planning for resource Johnny Marr for this week."
Search Appointments
Tool: search_appointments
Searches appointments by subject, date range, resource, or task.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
searchTerm | string | No | Search term to match against appointment subject or description |
startDate | string | No | Start date for date range filter (ISO 8601 format, e.g., 2024-01-01T00:00:00Z) |
endDate | string | No | End date for date range filter (ISO 8601 format, e.g., 2024-01-31T23:59:59Z) |
resourceDisplayName | string | No | Resource display name to filter by |
taskNo | string | No | Task number to filter by |
categoryName | string | No | Category name to filter by |
limit | number | No | Maximum number of results to return (default: 500) |
Example:
"Show John's appointments this week"
Get Appointment Details
Tool: get_appointment_details
Gets detailed information about a specific appointment. The appointment can be found by appointment number, task number, subject, resource, and day.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
appointmentNo | string | No | Appointment number (hashed ID) to identify the appointment directly by ID |
taskNo | string | No | Task number to identify the appointment (e.g., TASK-123) |
subject | string | No | Subject/title of the appointment |
resourceDisplayName | string | No | Resource display name to identify the appointment (highly recommended when task has multiple appointments) |
day | string | No | Day/date to find the appointment (ISO 8601 date with explicit year, e.g., 2026-01-07, or relative dates like today, tomorrow, Monday) |
startDateTime | string | No | Start date and time (alternative to day) - ISO 8601 datetime with explicit year |
Example:
"Get details for the appointment on task 123 tomorrow"
Create Appointment
Tool: create_appointment
Creates a new appointment for resource(s) at a specified time.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
subject | string | Yes | The subject/title of the appointment |
startDateTime | string | Yes | The start date and time (ISO 8601 format, e.g., 2024-01-01T09:00:00Z) |
endDateTime | string | Yes | The end date and time (ISO 8601 format, e.g., 2024-01-01T11:00:00Z) |
resourceDisplayNames | string | Yes | The display names of the resources to assign to this appointment (comma-separated, e.g., John Doe, Jane Smith) |
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
description | string | No | Description/body text for the appointment |
taskNo | string | No | Task number to link this appointment to a specific task (can be numeric like 24 or formatted like TASK-001) |
categoryName | string | No | Category name (e.g., Installation, Repair) |
timeMarkerName | string | No | Time marker name (e.g., Travel, Break) |
importance | number | No | Priority/importance level (0 = Medium, 1 = High, 2 = Low) |
Example:
"Schedule task 24 for John Smith tomorrow at 2 PM for 2 hours"
Update Appointment
Tool: update_appointment
Updates an existing appointment with new details. Only provide the fields you want to update. The appointment is found by appointment number, or by its subject and start date/time.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
appointmentNo | string | No | Appointment number (hashed ID) to identify the appointment directly by ID |
subject | string | No | The subject/title of the appointment to update (either appointmentNo or subject must be provided) |
currentStartDateTime | string | No | The current start date and time of the appointment (ISO 8601 format) |
resourceDisplayName | string | No | Resource display name to help find the correct appointment if multiple appointments have the same subject and date |
newSubject | string | No | New subject/title for the appointment |
startDateTime | string | No | New start date and time (ISO 8601 format) |
endDateTime | string | No | New end date and time (ISO 8601 format) |
description | string | No | New description/body text for the appointment |
resourceDisplayNames | string | No | New resource display names (comma-separated) - reassigns the appointment to these resources |
taskNo | string | No | Task number to link this appointment to a specific task |
categoryName | string | No | Category name for the appointment |
timeMarkerName | string | No | Time marker name for the appointment |
importance | number | No | Priority/importance level (0 = Medium, 1 = High, 2 = Low) |
Example:
"Update the appointment with subject 'Meeting' to start at 3 PM instead of 2 PM"
Reschedule Appointment
Tool: reschedule_appointment
Modifies an existing appointment: move to new date/time, change duration, and/or reassign to different resources. Only provide parameters that are explicitly specified.
Parameters:
Identification Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
appointmentNo | string | No | Appointment number (hashed ID) to identify the appointment directly by ID |
taskNo | string | No | Task number to identify the appointment |
subject | string | No | Subject/title of the appointment |
resourceDisplayName | string | No | Current resource display name to identify the appointment |
currentDay | string | No | Current day/date to find the appointment (ISO 8601 date with explicit year or relative dates like today, tomorrow) |
currentStartDateTime | string | No | Current start date and time (alternative to currentDay) - ISO 8601 datetime with explicit year |
Move Parameters (Change Start Time)
| Parameter | Type | Required | Description |
|---|---|---|---|
newDay | string | No | New day/date for the appointment (ISO 8601 date with explicit year or relative dates) |
newTime | string | No | New time for the appointment (e.g., 13:14, 14:00) - use this when only a time is specified |
relativeTimeShift | string | No | Relative time shift (e.g., 2 hours later, 30 minutes earlier) |
newStartDateTime | string | No | Exact new start date and time (ISO 8601 datetime with explicit year) |
Duration Parameters (Change End Time)
| Parameter | Type | Required | Description |
|---|---|---|---|
newDuration | string | No | New duration for the appointment (e.g., 2 hours, 90 minutes) |
newEndDateTime | string | No | Exact new end date and time (ISO 8601 datetime with explicit year) |
Resource Reassignment Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
newResourceDisplayNames | string | No | New resource display names for reassignment (comma-separated) |
Example:
"Move tomorrow's appointment for Jack Brugerling to next Monday at 2 PM"
Delete Appointment
Tool: delete_appointment
Deletes an existing appointment. The appointment can be identified by appointment number, or by subject and startDateTime.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
appointmentNo | string | No | Appointment number (hashed ID) to identify the appointment directly by ID |
subject | string | No | The subject/title of the appointment to delete (either appointmentNo or subject must be provided) |
startDateTime | string | No | The start date and time of the appointment (ISO 8601 format) |
resourceDisplayName | string | No | Resource display name to help find the correct appointment if multiple appointments have the same subject and date |
Example:
"Delete the appointment 'Meeting' scheduled for tomorrow at 2 PM"
Reference Data
List Categories
Tool: list_categories
Lists all available categories in the system.
Example:
"List all categories"
List Time Markers
Tool: list_time_markers
Lists all available time markers in the system.
Example:
"List all time markers"
Utility Tools
Parse Relative Time
Tool: parse_relative_time
Parses natural language relative time expressions into concrete date ranges. Returns both UTC and local time formats. Weeks start on MONDAY (not Sunday). Use this tool to convert relative time expressions to ISO 8601 dates before calling other tools that require specific date parameters.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
expression | string | Yes | Natural language relative time expression to parse (e.g., this week, next month, 5 days ago) |
timeZone | string | Yes | IANA timezone identifier (e.g., Europe/Brussels, America/New_York) |
referenceTime | string | No | Reference time in ISO 8601 format (if not provided, uses current time in the specified timezone) |
Supported expressions:
this week,next week,last week(Monday-Sunday)this month,next month,last monththis year,next year,last yeartoday,tomorrow,yesterday5 days ago,2 weeks from now,in 3 months, etc.
Example:
"Parse 'next week' in Europe/Brussels timezone"
Try it out
MCP Server Endpoint
The MCP server is available at:
- Sandbox:
https://sandbox.api.dimescheduler.com/mcp - Test:
https://test.api.dimescheduler.com/mcp - Production: Not available yet
Using the MCP Inspector
You can use the MCP Inspector to test and interact with the MCP server endpoint. The inspector provides a visual interface to explore available tools and test MCP functionality.
-
Install and run the MCP Inspector:
npx @modelcontextprotocol/inspector -
Configure the connection:
- Transport type: Streamable HTTP
- URL:
https://test.api.dimescheduler.com/mcp - Authentication: Custom headers
- Header name:
X-API-KEY - Header value: Your API key created in Dime.Scheduler
- Header name:
To create an API key in Dime.Scheduler:
- Navigate to the API Keys section in your Dime.Scheduler administration panel
- Create a new API key
- Copy the generated key value
- Use this key as the value for the
X-API-KEYheader in the MCP Inspector
Keep your API key secure and never share it publicly.
Open Source Playground
We have an open source playground that you can use to explore some of the capabilities of our MCP server. The playground provides a hands-on way to test and interact with the MCP integration.
GitHub Repository: dime-scheduler/mcp-examples
