Agent setup
Cursor + Caly
Below is the procedure the agent follows from /agent-setup/prompt.md, for when you would rather do it by hand.
1. Get an API key
Create one at Settings → Developer → API keys and keep it somewhere safe; Caly shows it once.
2. Configure Cursor
- Store the key in
.envasCALY_API_KEY=<key>. - Append the block below to
.cursor/rules/caly.mdc(create it if it does not exist). - Start .cursor/rules/caly.mdc with four frontmatter lines — ---, description: Caly scheduling API, alwaysApply: true, --- — so the rule loads in every chat.
- Add .env to .gitignore if it is not already there, so the key never lands in a commit.
## Caly Caly is the scheduling tool this project talks to. - MCP server: `Caly` at https://mcp.trycaly.com/mcp. It does everything the Caly app does. Call `search_tools` first, then run one `execute_typescript` program. Tool families: - Profile, preferences and account: whoami, get_profile, update_profile, update_notification_prefs, change_password, send_password_setup_email, ... - Event types: list_event_types, get_event_type, create_event_type, update_event_type, delete_event_type, list_private_links, ... - Slots: find_available_slots, reserve_slot, get_slot_reservation, update_slot_reservation, release_slot_reservation - Bookings: list_bookings, get_booking, create_booking, reschedule_booking, cancel_booking, confirm_booking, ... - Schedules and availability: list_schedules, get_schedule, get_default_schedule, create_schedule, update_schedule, delete_schedule, ... - Billing and plans: billing_status, list_plans, upgrade_plan, manage_subscription - Teams, members and invites: list_teams, list_team_invitations, accept_team_invitation, leave_team, create_team, update_team, ... - Support: create_support_ticket, list_support_tickets - Connected services: list_connections, get_connect_links, disconnect, reverify - API keys, OAuth apps and permissions: list_api_keys, create_api_key, rotate_api_key, revoke_api_key, list_granted_scopes, request_scopes, ... - Calendars: list_calendars, get_busy_times, set_destination_calendar, select_calendar, unselect_calendar, save_ics_feed, ... - Video apps: list_conferencing_apps, get_default_conferencing, set_default_conferencing, connect_conferencing, disconnect_conferencing - Verified emails and phones: request_email_verification, verify_email, request_phone_verification, verify_phone, list_verified_emails, list_verified_phones, ... - Time off: list_out_of_office, create_out_of_office, update_out_of_office, delete_out_of_office, list_ooo_reasons - Holidays and travel: get_holiday_settings, update_holiday_settings, toggle_holiday, list_holiday_countries, check_holiday_conflicts, get_travel_schedules, ... - Webhooks: list_webhooks, get_webhook, create_webhook, update_webhook, delete_webhook, test_webhook - App catalog: get_app, list_app_catalog, list_location_options, update_app_credentials - Saved table filters: list_saved_filters, create_saved_filter, update_saved_filter, delete_saved_filter, set_default_saved_filter Destructive actions (cancel or decline a booking, delete anything, remove a member, cancel a subscription, delete the account) are two-step: the first call returns CONFIRMATION_REQUIRED with a confirmToken; tell the user exactly what will happen, then call again with the SAME arguments plus that confirmToken. Every refusal has a `next` field naming the tool to call (for example `request_scopes` for a missing permission, `upgrade_plan` for a plan limit). To upgrade or manage billing call `upgrade_plan` or `manage_subscription`; you get a one-tap link, and card details are only entered on that page. - REST API for everything else: base URL https://api.trycaly.com — every endpoint lives under /v2 - Auth: send the key from the CALY_API_KEY environment variable as `Authorization: Bearer <key>` - Booking endpoints are versioned: send `cal-api-version: 2024-08-13` on /v2/bookings requests - OpenAPI spec (source of truth for paths and payloads): https://trycaly.com/docs/openapi.json - Human reference: https://trycaly.com/docs/api/ - Outbound webhooks (booking created / rescheduled / cancelled) are created with the `create_webhook` tool (account-wide) or `create_event_type_webhook` (one event type); they are listed at https://app.trycaly.com/settings/developer/webhooks Never print the key. Prefer reading the spec over guessing an endpoint.
3. Connect the MCP server
Caly's MCP server at https://mcp.trycaly.com/mcp takes the same API key. For Cursor the connection lives in ~/.cursor/mcp.json (user level, outside the repository).
- Merge the Caly entry below into ~/.cursor/mcp.json (create the file if needed; keep any servers already there), with the key in place of <key>. Never put this entry in the project's .cursor/mcp.json: that file can be committed.
- Tell the user to reload MCP servers from the MCP page of Cursor's settings so Caly shows up.
{
"mcpServers": {
"Caly": {
"url": "https://mcp.trycaly.com/mcp",
"headers": { "Authorization": "Bearer <key>" }
}
}
}4. Verify
curl -s -H "Authorization: Bearer $CALY_API_KEY" https://api.trycaly.com/v2/me
curl -s -X POST https://mcp.trycaly.com/mcp -H "Authorization: Bearer $CALY_API_KEY" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'The first returns a JSON profile with your email; the second returns the MCP server's tool list. A 401 from either means the key is missing, expired or mistyped.
Other agents: all guides.