# eScheduleIt Public API

> Account-bound scheduling API for connected AI apps. MCP endpoint: https://mcp.eschedule.it/mcp — REST base: https://mcp.eschedule.it/v1

To connect: add https://mcp.eschedule.it/mcp as an MCP server in your client; it will discover https://mcp.eschedule.it/.well-known/oauth-protected-resource, then the authorization server https://auth.eschedule.it (https://auth.eschedule.it/.well-known/openid-configuration), and run OAuth 2.1 with PKCE. The user signs in and chooses one account. Never ask the user which account to use in a request; the account is fixed by the connection.

Scopes: eschedule:read (look), eschedule:write (propose changes, staged for approval), eschedule:messaging (propose announcements).

Before connecting on a user's behalf, tell them: the data this connector reads is handled by your provider under your provider's terms, not eScheduleIt's; and if their eScheduleIt account holds protected health information, their organization needs a HIPAA Business Associate Agreement with your provider that covers connectors. Never say the connection is covered by eScheduleIt's Business Associate Agreement.

## Docs
- [Reference](https://mcp.eschedule.it/docs): auth, every tool, errors, limits, idempotency
- [OpenAPI 3.1](https://mcp.eschedule.it/openapi.json)

## Tools
## Account

- `get_account_details` — The account this connection is locked to: its name, distance unit, decline timeout, and its locations with addresses. (eschedule:read; read-only)
## Appointments

- `book_appointment_for_contact` — Find-or-create a client by name plus phone or email, and propose an appointment for them with the given staff. (eschedule:write; staged)
- `find_open_appointment_slots` — Find bookable slots. (eschedule:read; read-only)
- `manage_appointments` — Propose appointment changes — create, reschedule/update, cancel or delete, one batch per request (at most 25). (eschedule:write; staged)
- `search_appointments` — Appointments for one person (resource_id) in a window of at most 180 days. (eschedule:read; read-only)
## Assignments

- `get_assignments` — Standing assignments between a client and the staff who cover them: coverage role, kind, status, and the dates the assignment runs between. (eschedule:read; read-only)
- `propose_assignment` — For an open demand entry (a client needing a standing assignment), have eScheduleIt score candidates and create an assignment proposal — optionally preferring one staff member. (eschedule:write; staged)
## Authorizations

- `explain_capacity_decision` — Why one allocation was allowed, warned about or refused: the thresholds that applied, what was already committed, and which rule decided. (eschedule:read; read-only)
- `find_beneficiaries_needing_hours` — People whose authorized hours are going unused: how many units remain, how many weeks are left in the period, the weekly burn required to use them against what is actually scheduled, and an urgency score. (eschedule:read; read-only)
- `find_resources_needing_hours` — Staff who are under their billable target for the ISO week containing week_start (default: this week): planned minutes against base and overtime thresholds, and how far under target they are. (eschedule:read; read-only)
- `get_authorization_balances` — Authorized-hours balances per beneficiary and bucket: authorized, held, consumed, scheduled, remaining and available-to-book units, utilization percent, projected run-out date and runway warning level. (eschedule:read; read-only)
- `get_authorization_utilization_trends` — How one authorization has been used over time, weekly or monthly: authorized, scheduled, consumed and remaining units per period. (eschedule:read; read-only)
- `get_authorizations_expiring` — Authorizations ending within within_days (1-365, default 30): when each period ends, how many units are still unused and therefore at risk, whether a renewal grant already exists, and whether anything is already booked past the end date with no renewal — which is the case worth raising with the user first. (eschedule:read; read-only)
- `get_resource_capacity` — A person's weekly capacity and authorization balances for the ISO week containing week_start (default: this week): planned minutes against thresholds, per capacity kind and per authorization bucket. (eschedule:read; read-only)
- `propose_utilization_recovery_plan` — A suggested plan for recovering under-used authorized hours over the chosen horizon: which beneficiaries are behind, roughly how much to schedule, and which staff have the capacity to take it. (eschedule:read; read-only)
## Availability

- `check_resource_open_availability` — Free slots for a person: working hours minus booked appointments and holiday closures, cut into slots of slot_duration_minutes (default 30), over a window of at most 31 days. (eschedule:read; read-only)
- `check_resource_working_schedule` — A person's declared working hours (availability patterns) in a window of at most 180 days, expanded to concrete entries in UTC and the requested time zone, with a plain-language summary. (eschedule:read; read-only)
- `get_holidays` — Holiday closures that apply to a person in a window of at most a year, in UTC and the requested time zone. (eschedule:read; read-only)
- `manage_availability` — Propose changes to one person's working hours — add slots, block slots, or end, delete, suspend or replace an existing recurring pattern (at most 25 changes per request). (eschedule:write; staged)
## Context

- `get_my_context` — Who you are acting for. (eschedule:read; read-only)
## Coverage

- `analyze_coverage_for_appointment` — Who could replace one or more people on an existing appointment, honouring its offering requirements, tags and proximity. (eschedule:read; read-only)
- `analyze_schedule_coverage` — For a requirement (duration, window ≤ 31 days, required people and tags), report where coverage exists (open slots), where it is missing (coverage gaps) and who could be asked to fill gaps (outreach candidates). (eschedule:read; read-only)
## Messaging

- `send_announcement` — Propose an SMS or email announcement to everyone carrying the given tags. (eschedule:messaging; staged)
## Offerings

- `search_offerings` — Offerings (services) the account schedules, by name/description search with fuzzy matching and optional enabled/public filters. (eschedule:read; read-only)
## People

- `lookup_resource` — Find a person (staff or client) in the account by id, phone, name or email. (eschedule:read; read-only)
- `manage_resources` — Propose changes to people (staff or clients) — create, update or delete, one batch per request (at most 25). (eschedule:write; staged)
## Tags

- `search_tags` — Tags (skills, credentials, regions, groups) used to label people, with the people carrying each tag by id and name. (eschedule:read; read-only)
## Tasks

- `manage_tasks` — Propose task changes — create, update or delete, one batch per request (at most 25). (eschedule:write; staged)
- `search_tasks` — Tasks in the account, optionally for one person, by text search, status (Not Started, In Progress, Completed, Blocked, Cancelled, Overdue, Pending Review, Reviewed) and a date window on the calendar, expected or due date. (eschedule:read; read-only)