Agent setup

OpenCode + 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 OpenCode

  1. Store the key in .env as CALY_API_KEY=<key>.
  2. Append the block below to AGENTS.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.
## 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 OpenCode the connection lives in ~/.config/opencode/opencode.json (global, outside the repository).

  1. Merge the Caly entry below into ~/.config/opencode/opencode.json (create the file if needed; keep everything already there). It names the variable, never the key.
  2. This agent reads CALY_API_KEY from the environment it was started in, not from .env. Tell the user to add export CALY_API_KEY=<key> to their shell profile, or to start the agent from this project with set -a; . ./.env; set +a first.
  3. Tell the user to restart OpenCode so the Caly server loads.
{
  "mcp": {
    "Caly": {
      "type": "remote",
      "url": "https://mcp.trycaly.com/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env: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.