How to connect Calendly MCP with TypeScript

Use: List all named availability schedules for the connected user. When: User asks about availability schedules or you need to identify one by name. Needs: User URI from `users-get_current_user`. Do: Use returned `uri` to fetch schedule details or associate with an event type. Avoid: Confusing user availability schedules with event-type-level schedules. Then: Use schedule URI in `availability-get_user_availability_schedule` for details.

Use: Fetch details for one named availability schedule. When: User asks about specific schedule rules or needs rules for a named schedule. Needs: Schedule URI from `availability-list_user_availability_schedules`. Do: Read `rules` array and `timezone` for display or to inform event-type updates. Avoid: Writing to this schedule—use event-type-level update for changes. Then: Report schedule details to user or use rules for availability queries.

Use: List a user's busy time blocks within a date range. When: User asks a general yes/no "what's my schedule", "am I free/busy", or "do I have any meetings" question with no named event type, invitee, or specific meeting. Default here even when the user says "meetings" — see `meetings-list_events` instead when the user wants to see or list which meetings they have. Needs: User URI from `users-get_current_user` and ISO 8601 start/end range. Do: Pass user URI and date range; use returned intervals to report conflicts. Avoid: Substituting for `event_types-list_event_type_available_times` (event-type bookable slots) or `meetings-list_events` (only booked Calendly meetings, not full calendar busy blocks) — they differ. Then: Use busy intervals to inform scheduling recommendations.

Use: Create a new event type on the connected account. When: User explicitly asks to create a new event type. Needs: Host user URI from `users-get_current_user`. Do: Set name, duration, and host URI; omit optional fields unless user specified them. Avoid: Creating duplicates—call `event_types-list_event_types` first to check for existing types. Then: Confirm the new event type URI and share the scheduling URL.

Use: Update fields on an existing event type. When: User asks to change name, duration, description, or other settings. Needs: Event type URI from `event_types-list_event_types` or `event_types-get_event_type`. Do: Read current state first with `event_types-get_event_type`; patch only requested fields. Avoid: Sending fields not read from current state—partial writes may reset unset fields. Then: Confirm changes with `event_types-get_event_type`.

Use: List all event types for the connected user or org. When: Start of any event-type task, or when selecting an event type by name. Needs: User URI from `users-get_current_user`. Do: Filter by current user URI unless user explicitly asks about a different host or org. Avoid: Assuming a cached list is current—call fresh each session. Then: Carry the selected `uri` into get, update, or availability tools.

Use: Fetch full details for one event type by URI. When: Before updating an event type or confirming its current configuration. Needs: Event type URI. Do: Use the returned fields as the baseline for any patch payload. Avoid: Constructing update payloads without reading current state first. Then: Proceed with `event_types-update_event_type` using the returned data as base.

Use: List bookable time slots for an event type within a date range. When: User wants slots, or to confirm availability before booking. Needs: Event type URI and start/end date range (ISO 8601). Do: Pass `start_time` verbatim to subsequent tool calls; do not rewrite UTC values. Avoid: Stale data, or trusting a prior local label—re-check UTC `start_time` if questioned. Then: Pass UTC `start_time` to `meetings-create_invitee`.

Use: Read the current availability schedule (rules) for an event type. When: Before calling `event_types-update_event_type_availability_schedule`. Needs: Event type URI. Do: Retain the full `rules` array verbatim—it is the required base for updates. Avoid: Calling the update endpoint without first reading the current rules. Then: Pass the rules to `event_types-update_event_type_availability_schedule` with only the needed edits.

Use: Overwrite the availability schedule for an event type. When: User requests schedule changes (hours, days, one-off date overrides) for an event type. Needs: Event type URI and current rules from `event_types-list_event_type_availability_schedule`. Do: Must copy existing rules verbatim, modify only requested entries, send full rules array with IANA timezone. wday rules need `wday` field; date rules need `date` field (YYYY-MM-DD); `intervals` is list of `{from, to}` in HH:MM 24h. Avoid: Constructing rules from scratch or sending a partial array—this endpoint overwrites all rules. Then: Re-read schedule with `event_types-list_event_type_availability_schedule` to confirm.

Use: List allowed meeting location kinds for a user. When: Before creating bookings that need a `location` payload. Needs: User URI from `users-get_current_user`. Do: Read supported location `kind` values; choose one compatible with the event type. Avoid: Submitting a location kind not configured for the host or event type. Then: Use chosen kind in `meetings-create_invitee` location payload.

Use: List scheduled meetings for user/org. When: Upcoming/past meetings or to find meetings by date. Needs: User/org URI via `users-get_current_user`. Do: Filter status (active/canceled), date range; carry `uri`. Avoid: Fetching unfiltered when the user has a specific date. Not for a yes/no busy/free check phrased as "meetings" (e.g. "do I have any meetings tomorrow") — use `availability-list_user_busy_times` instead. Then: Enrich via `meetings-list_event_invitees` before listing/naming meetings, unless asked for only a count; then `uri` in `meetings-get_event`/`meetings-cancel_event`.

Use: Fetch details for a single scheduled meeting. When: User asks about a specific meeting or before canceling/examining invitees. Needs: Meeting URI from `meetings-list_events`. Do: Use returned `event_type`, `start_time`, `end_time`, and `location` for display or next actions. Avoid: Calling this without a known meeting URI. list meetings first. Then: Use meeting URI in `meetings-list_event_invitees` or `meetings-cancel_event`.

Use: Cancel a scheduled meeting on behalf of the connected host When: User confirms they want to cancel a specific meeting. Needs: Meeting URI from `meetings-list_events` or `meetings-get_event`. Do: Pass meeting URI and optional cancellation reason. Avoid: Canceling without confirmation; this notifies all invitees. For reschedule, surface `reschedule_url` instead. Then: Inform user the meeting is canceled and optionally list remaining meetings.

Use: Book a meeting slot for an invitee on a Calendly event type. When: User provides invitee name, email, and a confirmed available time slot. Needs: Event type URI, `start_time` from `event_types-list_event_type_available_times`, invitee name and email. Include `location` if the event type has configured locations. Do: Set invitee name/email as the person being booked; host is the connected user from `users-get_current_user`. Never swap host and invitee fields. Avoid: Booking without confirming slot availability first, or omitting `location` when event type requires it. Then: Confirm booking with invitee details and meeting URI.

Use: List all invitees for a scheduled meeting. When: User asks who is attending a meeting or you need invitee URIs. Needs: Meeting URI from `meetings-list_events`. Do: Use returned invitee `uri` for no-show marking or detail lookups. Avoid: Calling without a meeting URI. list meetings first. Then: Use invitee URI in `meetings-get_event_invitee` or `meetings-create_invitee_no_show`. For reschedule, surface each invitee's `reschedule_url`.

Use: Fetch details for a single meeting invitee. When: User asks about a specific attendee's booking details. Needs: Meeting URI from `meetings-list_events` and Invitee URI from `meetings-list_event_invitees`. Do: Use returned fields for display or no-show status. Reschedule: surface `reschedule_url`. Avoid: Calling without known meeting and invitee URIs. Then: Use invitee URI in no-show tools if needed.

Use: Mark an invitee as a no-show for a past meeting. When: User reports an invitee did not attend. Needs: Invitee URI from `meetings-list_event_invitees`. Do: Pass invitee URI; operation is idempotent. Avoid: Marking no-show before the meeting end time. Then: Confirm no-show is recorded and carry forward the no-show URI.

Use: Fetch the no-show record for a meeting invitee. When: User asks whether a no-show was recorded for an invitee. Needs: No-show URI from `meetings-create_invitee_no_show`. Do: Check returned record for no-show status and timestamp. Avoid: Calling if no no-show has been recorded—returns 404. Then: Report no-show status to user.

Use: Remove a no-show mark from an invitee. When: User asks to undo a no-show marking. Needs: No-show URI from `meetings-create_invitee_no_show`. Do: Pass no-show URI; operation is idempotent. Avoid: Calling without confirming a no-show record exists. Then: Confirm no-show has been removed.

Use: Fetch details for the connected user's organization. When: User asks about the org or you need the org URI for org-scoped list tools. Needs: Org URI from `users-get_current_user` (`resource.current_organization`). Do: Use returned `uri` for org-scoped event type or membership queries. Avoid: Calling without an org URI. Then: Use org URI in `organizations-list_organization_memberships`.

Use: List all members of an organization. When: User asks who is in the org or you need to find a member's user URI. Needs: Org URI from `users-get_current_user`. Do: Use returned `user.uri` for per-user event-type or availability queries. Avoid: Fetching the full list when you only need the connected user—use `users-get_current_user` instead. Then: Use member URI in user-scoped tools or `organizations-get_organization_membership`.

Use: Fetch details for a single org membership. When: You need role or status for a specific member. Needs: Membership URI from `organizations-list_organization_memberships`. Do: Check `role` and `status` fields for permissions context. Avoid: Calling without a known membership URI. Then: Use membership data to confirm before invite or removal actions.

Use: List pending invitations for the organization. When: User asks to see pending invites or check if someone was already invited. Needs: Org URI from `users-get_current_user`. Do: Check returned list before sending a new invite to avoid duplicates. Avoid: Sending a new invitation without checking for existing pending ones. Then: Use invitation URI in `organizations-revoke_organization_invitation` if needed.

Use: Invite a user to the organization by email. When: User asks to add a new member. Needs: Org URI and invitee email address. Do: Check `organizations-list_organization_invitations` first to avoid duplicate invites. Avoid: Calling without confirming no pending invite exists for this email. Then: Confirm invitation sent and optionally show pending invitations.

Use: Revoke a pending organization invitation. When: User asks to cancel a pending invite. Needs: Organization URI from `users-get_current_user` and Invitation URI from `organizations-list_organization_invitations`. Do: Confirm with user before revoking; this cannot be undone. Avoid: Revoking without confirming the invite is still pending. Then: Confirm revocation and optionally refresh invitations list.

Use: List routing forms for the org. When: User asks about routing forms or you need to find a form by name. Needs: Org URI from `users-get_current_user`. Do: Use returned `uri` to fetch form details. Avoid: Assuming form names without listing first. Then: Use form URI in `routing_forms-get_routing_form`.

Use: Fetch details for a single routing form. When: User asks about a specific form or its questions. Needs: Routing form URI from `routing_forms-list_routing_forms`. Do: Use returned question IDs for submission filtering. Avoid: Calling without a known form URI. Then: Use form details to answer user questions or list submissions.

Use: List submissions for a routing form. When: User asks to see form responses or analyze routing data. Needs: Routing form URI from `routing_forms-list_routing_forms`. Do: Use pagination params for large result sets. Avoid: Fetching all submissions without date/count filters on high-volume forms. Then: Use submission URI in `routing_forms-get_routing_form_submission`.

Use: Fetch details for a single routing form submission. When: User asks about a specific submission or response. Needs: Submission URI from `routing_forms-list_routing_form_submissions`. Do: Read `questions_and_answers` for the submitted values. Avoid: Calling without a known submission URI. Then: Report submission details to user.

Use: Create a single-use scheduling link using the event type's settings unchanged. When: User wants a one-time link with no overrides. For per-link customization (duration, scheduling window, location, availability), use `shares-create_share` instead. Needs: Event type URI from `event_types-list_event_types`. Do: Each call creates a new link; store the returned `booking_url`. Avoid: Using when any override is requested — this endpoint cannot customize the link. Don't create more links than needed; each call creates a distinct non-reusable link. Then: Share `booking_url` with the intended invitee.

Use: Create a single-use share link for a one-on-one event type with per-link overrides When: User wants a single-use link with any customization (duration, scheduling window, location, or availability). Needs: Event type URI from `event_types-list_event_types`. Do: Set only fields to override; omitted fields inherit from event type. Avoid: Group event types (one-on-one only). Then: Share the returned `booking_url`. To prefill the invitee's name on the booking page, append a `name` query parameter with the URL-encoded value, e.g. `{booking_url}?name=Pat+Tester`.

Use: Resolve the connected host account and canonical user URI. When: Start any scheduling, booking, event-type, or availability workflow. Needs: No inputs. Do: Call once and keep `resource.uri`, `timezone`, and `scheduling_url` for downstream calls. Avoid: Skipping this and guessing host identity. Then: Use `resource.uri` in list/get tools unless the user explicitly names another host.

Use: Fetch profile for a specific user by URI. When: User asks about another person's account or you hold a user URI from org/membership data. Needs: User URI. Do: Pass the user URI from org/membership data; do not use this to look up the connected user. Avoid: Calling this without a known URI - use `users-get_current_user` for the connected user. Then: Use returned `resource.uri` and `resource.timezone` for event-type or availability lookups scoped to that user.

List or search available Calendly skill guides. Each skill gives domain-specific context, recommended tool usage, and best practices for working with Calendly MCP tools. Call this when the user's goal has no obvious single tool (e.g. reschedule or move a meeting). Load a matching skill before using related workflow tools. Use `keywords` to search by name or description (any keyword may match), and `include_header=true` to include each skill's description and related skills.

Load a Calendly skill guide that provides domain-specific context, recommended queries, and best practices for working with Calendly tools. Required after listing when a skill matches; do not guess multi-step flows from tool names alone. Use `list_calendly_skills` to discover available skills, or load directly by name. Set `header_only=true` to preview a skill's description and related skills without loading full content.