Agent setup

Claude Code + 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 Claude Code

  1. Store the key in .env as CALY_API_KEY=<key>.
  2. Append the block below to CLAUDE.md (create it if it does not exist).
  3. Add .env to .gitignore if it is not already there, so the key never lands in a commit.
  4. Tell the user they can start a Caly task in this project with plain language now, e.g. "list my event types".
## 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 Claude Code the connection lives in ~/.claude.json (local scope: private to this user and this project).

  1. Run the commands below from the project root. The default local scope keeps the key out of .mcp.json and out of the repository.
  2. Tell the user to restart Claude Code (or open /mcp) so the Caly server loads.
set -a; . ./.env; set +a
claude mcp add --transport http Caly https://mcp.trycaly.com/mcp --header "Authorization: Bearer $CALY_API_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.