Agent quickstart

Connect this environment to Kyo (https://www.trykyo.com) — my agency's workspace for
CRM, tasks, projects, and more. Follow the steps in order and tell me what you did
after each one.

Ground rules
- Never print token values or the contents of credential files; refer to them by
  name only.
- The Kyo API is non-destructive: v1 has no DELETE. Do not attempt to delete
  anything.
- Company enrichment (kyo_enrich_company / POST /v1/enrich) spends paid workspace
  credits — skip it unless I explicitly ask.
- Ask me before creating or updating more than a handful of records.

Step 1 — Pick the connection
If you can use MCP tools (Claude Code, Claude Desktop, Cursor, or another
MCP-capable client), set up the Kyo MCP server (Step 2). Otherwise use the REST
API directly (Step 3).

Step 2 — MCP setup (preferred)
0. Remote-capable client (claude.ai connectors, Claude Code, Cursor, or any MCP
   client that supports remote servers)? Skip the install — connect to the
   hosted server: https://app.trykyo.com/api/mcp
   - If I gave you a Kyo agent key (it starts with kagt_), send it on every
     request as the header  Authorization: Bearer <key>  — no browser step.
     Cursor: add "headers": {"Authorization": "Bearer <key>"} next to "url"
     in ~/.cursor/mcp.json. Claude Code: claude mcp add --transport http kyo
     https://app.trykyo.com/api/mcp --header "Authorization: Bearer <key>"
   - Otherwise connect with the URL alone and complete the browser sign-in it
     opens (Claude Code: claude mcp add --transport http kyo
     https://app.trykyo.com/api/mcp). I will approve the scopes.
   Then jump to step 5. Otherwise set up the local stdio server:
1. Check Node.js 18+ and npm are available: node -v
2. Install the CLI: npm install -g kyo-cli
3. Run: kyo login
   This opens a browser for OAuth sign-in. I will complete it — wait for the
   command to finish, then confirm the connection with: kyo whoami
4. Register the MCP server with the client you are running in:
   - Claude Code:     claude mcp add kyo -- npx -y kyo-cli mcp
   - Claude Desktop:  add {"mcpServers": {"kyo": {"command": "npx", "args":
                      ["-y", "kyo-cli", "mcp"]}}} to claude_desktop_config.json
   - Cursor:          add {"mcpServers": {"kyo": {"command": "kyo", "args":
                      ["mcp"]}}} to ~/.cursor/mcp.json
   - Other stdio MCP clients: command npx, args ["-y", "kyo-cli", "mcp"]
5. After the client restarts it discovers 118 kyo_* tools (kyo_list_deals,
   kyo_create_task, kyo_list_income, kyo_list_team_members, ...). Verify by
   calling kyo_whoami.
Full guide: https://www.trykyo.com/docs/mcp

Step 3 — REST API (no MCP)
- Base URL: https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1
- Every request needs two headers:
    Authorization: Bearer (a kyo_at_... access token)
    apikey: (the public anon key published at https://www.trykyo.com/docs/api#auth)
- Tokens come from the OAuth 2.0 + PKCE flow: https://www.trykyo.com/docs/oauth
  Access tokens last 1 hour; refresh tokens rotate on every use.
  If a browser sign-in is easier, install kyo-cli (Step 2.1–2.3) and shell out to
  it instead — kyo deals list, kyo tasks create --name "...", output is JSON.
- GET /v1/me returns who the token belongs to, its workspace and its scopes —
  call it first.
- Resources under /v1 (44 of them) cover CRM (deals, people, companies,
  pipelines, pipeline_stages, deal_tasks, deal_people, deal_labels, crm_files),
  work (tasks, task_attachments, spaces, projects, project_stages,
  space_members, space_updates, labels, comments), metrics (metrics,
  metric_pages, metric_entries), finance (income, expenses, finance_categories,
  debts, debt_payments), HR (team_members, departments, leave_requests,
  hr_contracts, hr_change_requests, org_chart), library (documents, knowledge,
  canvases), automations (automations, automation_logs), research
  (competitor_workflows, competitor_reports), agents, and the workspace
  directory (users, workspace, activity, credits). Plus enrich (POST-only,
  metered). Read-only: activity, credits, automation_logs, task_attachments,
  crm_files, competitor_*, agents.
- Reads: GET /v1/deals?limit=50 — keyset pagination via next_cursor (limit max
  200), plus exact-match filters like ?pipeline_id=...
- Writes: POST /v1/(resource) to create, PATCH /v1/(resource)/(id) to update.
  DELETE returns 405 everywhere.
- Rate limits: 60 requests/min per token, 600/min per workspace. On 429, honor
  Retry-After.
- Errors are JSON: {"error": "code", "message": "...", "request_id": "..."} —
  403 insufficient_scope means the token lacks resource:read / resource:write;
  403 insufficient_permission means I don't have that feature in the workspace,
  which no scope can override.
Full reference: https://www.trykyo.com/docs/api

Step 4 — Verify and report back
1. Confirm the connection: call the kyo_whoami tool, run kyo whoami, or
   GET /v1/me. Then list my pipelines (kyo_list_pipelines or GET /v1/pipelines).
2. Tell me which user or agent and which workspace you are connected as, which
   scopes you hold, and the names of my pipelines.
3. Suggest 3 useful things you could do from here (for example: turn TODOs in
   this repo into Kyo tasks, create deals from a lead list, or post a comment on
   a deal when a deploy ships) — and wait for my approval before writing
   anything.