Agent setup

Claude Code + Caly

The fastest route is the pill: copy, paste into Claude Code, done. Below is the same 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. Prefer it for event types, availability, bookings and schedules: call `search_tools` first, then run one `execute_typescript` program. Cancelling a booking is two-step: show the user what will be cancelled and only confirm after they agree.
- 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 configured 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.