# Harmony — Agent quickstart

You are an AI coding agent. This page wires Harmony's MCP server and the `/hmy`
skills into the current project so you can drive the board from the terminal.

If you don't have an API key yet, do <https://gethmy.com/auth.md> first.

## Inputs

From <https://gethmy.com/auth.md> you should have:

- `HARMONY_API_KEY` — starts with `hmy_`
- `HARMONY_WORKSPACE_ID`
- `HARMONY_PROJECT_ID`

Requires `npx` (Node ≥ 18).

## Option A — local install (recommended)

One command installs the MCP server, registers it with your agent, and writes
the `/hmy*` skills. `--yes` runs it fully unattended:

```bash
npx @gethmy/mcp@latest setup \
  --api-key "$HARMONY_API_KEY" \
  --workspace "$HARMONY_WORKSPACE_ID" \
  --project "$HARMONY_PROJECT_ID" \
  --global \
  --agents claude \
  --skip-docs \
  --yes
```

- Swap `--agents claude` for `codex`, `cursor`, or `windsurf` — or list several:
  `--agents claude cursor`.
- `--global` installs the skills for every project; use `--local` to scope them
  to this repo only.
- **The `--api-key … is deprecated and insecure` warning is expected here — it is
  not an error, don't bail.** It fires because the key sits in argv; that is fine
  for this unattended path (a human doing an interactive setup uses browser
  sign-in instead, with no `--api-key`).
- **`--yes`** answers setup's `y/n` confirmations (`Proceed with setup?`, then a
  tool-allowlist prompt) with their defaults, so the run doesn't stall on a
  keypress in a non-interactive shell. (Needs `@gethmy/mcp` ≥ 2.19.0; on older
  versions prefix the command with `yes |` instead.) In a real terminal you can
  drop `--yes` and answer the prompts yourself.

Verify:

```bash
npx @gethmy/mcp status   # expect: "Status: Configured" with your workspace + project
```

## Option B — hosted MCP (no install, no local Node runtime)

Point your agent at the hosted endpoint (signs in via the browser):

```bash
claude mcp add harmony --transport http https://mcp.gethmy.com/mcp
```

Any MCP-capable client works the same way — see <https://gethmy.com/docs/mcp>.

## Start working

Your new board has a sample card **#1**. Kick off the loop:

- **Claude Code:** `/hmy #1`
- **Codex:** `/prompts:hmy #1`
- **Cursor / other MCP clients:** the `harmony_*` tools are available
  automatically — ask to start card #1.

From here you claim cards, stream progress to the board as you work, and move
cards through the loop — build → review → shipped PR — alongside your human.