Codex + Caly

1. Get an API key

Create one at Settings → Developer → API keys and keep it somewhere safe; Caly shows it once.

2. Configure Codex

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. 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 Codex the connection lives in ~/.codex/config.toml.

1. Append the block below to ~/.codex/config.toml (create the file if needed; skip if a [mcp_servers.caly] table is 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 Codex so the caly server loads.

[mcp_servers.caly]
url = "https://mcp.trycaly.com/mcp"
bearer_token_env_var = "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.