---
name: hcp-setup
description: Set up HCP (Harness Context Protocol) in the current repository for the agent you are running in. Use when the user asks to install HCP, add HCP packs, or connect Claude Code, Cursor, Codex, OpenCode, or another MCP client to HCP.
---

# Set up HCP in this repository

You are an agent. Follow these steps in order, run every `hcpx` command with
`--json`, and read the result before the next step. Stop and ask the user only
where a step says so. The full documentation is at https://harnesscontextprotocol.io/docs

## Rules

- Type `hcpx`. The HCP CLI installs the same program as `hcp` and `hcpx`, but
  an unrelated tool also installs a binary named `hcp`.
- The CLI prints follow-up commands (`next`, `run`, `hint`) as `hcp …`; run
  them as `hcpx …`.
- Never write a token, key, or password into any file, config, or Skill,
  because HCP mints credentials at exec time and packs never hold them.
- Never pass `confirm=true` to `hcpx exec` unless the user has just approved
  that exact write in this conversation.
- Give the host one tool, `hcp`. Never register one tool or one MCP server per
  pack.
- Ask before editing any file outside this repository, except to install the
  CLI in step 1.
- If a step fails twice, stop and report the JSON error to the user.

## 1. Make sure `hcpx` runs

```bash
hcpx doctor --json
```

Expect `"ok": true`, `"protocol": "hcp"`, and `"bootstrap": "hcp-cli"`. If
`hcpx` is not found, run the same check through npx, which needs no install:

```bash
npx -y @harnesscontextprotocol/cli doctor --json
```

If that answers, install the CLI so the host can start it in step 4:
`npm install -g @harnesscontextprotocol/cli` (Node 20.11 or newer) or
`bun add -g @harnesscontextprotocol/cli`. If you cannot install it, run every
command below as `npx -y @harnesscontextprotocol/cli <command>` in place of
`hcpx <command>`, and tell the user the host needs the CLI installed.

If the package is not reachable (during the private preview it is on GitHub
Packages and needs a token that can read the `harnesscontextprotocol`
packages), install from source. This needs Bun and puts `hcpx` in
`~/.local/bin`, which must be on `PATH`:

```bash
git clone https://github.com/harnesscontextprotocol/hcp ~/.hcp-src
(cd ~/.hcp-src && bun install)
mkdir -p ~/.local/bin
printf '#!/bin/sh\nexec bun "$HOME/.hcp-src/packages/cli/src/hcp.ts" "$@"\n' > ~/.local/bin/hcpx
chmod +x ~/.local/bin/hcpx
```

If none of these works, stop and tell the user what failed. Otherwise run
`hcpx doctor --json` again before continuing.

## 2. Know your host

Use the product you are running in to pick the adopt steps in step 4. If you
are unsure which it is, these files hint at the host: `.cursor/` for Cursor,
`CLAUDE.md` or `.claude/` for Claude Code, `opencode.json` for OpenCode, and
`AGENTS.md` together with `~/.codex/` for Codex.

## 3. Install and activate packs

- If the user named tools or CLIs, search the catalog for each:

  ```bash
  hcpx search <name> --json
  ```

  Install a hit with the `install.cli` line of its catalog entry, run as
  `hcpx` and with `--json`, for example `hcpx install github:owner/repo --json`.
- Install any pack directory in this repository (a folder that contains
  `surface.json`, `policy.json`, and `HARNESS.md`):

  ```bash
  hcpx install ./path/to/pack --json
  ```

- Activate everything you installed:

  ```bash
  hcpx activate <pack_id> [<pack_id> …] --json
  ```

If nothing matches, the bootstrap pack `hcp-cli` is enough to finish setup. If
the user wants a CLI that has no pack yet, follow https://harnesscontextprotocol.io/wrap.md after this
runbook.

## 4. Adopt into your host

| Host | Do this |
|------|---------|
| Claude Code | `hcpx adopt claude --write`. It writes `.claude/skills/hcp/SKILL.md`, one `hcp` server in `.mcp.json`, and `.claude/settings.json`; Claude Code asks the user to approve the server on its next start. |
| Codex | `hcpx adopt codex --write`. It writes `.hcp/skills/hcp/SKILL.md` and an HCP section in `AGENTS.md`, and returns a `[mcp_servers.hcp]` block in `preview.codex_config.append`. Ask the user before adding that block to `~/.codex/config.toml`. |
| Cursor | `hcpx adopt cursor --write` |
| OpenCode | `hcpx adopt opencode --write` |
| Grok | `hcpx adopt grok --write` |
| Any other MCP client | `hcpx adopt mcp --write`, then register the `hcp` server from `.hcp/mcp.json` in the client's MCP config. |

Run the adopt command without `--write` first to preview the files. `cli_bin`
in the result names the binary the host will start. If the result has a `note`
that the CLI is not on PATH, install it (step 1) before the host starts.

## 5. Connect packs that need a login

```bash
hcpx availability --json
```

Each pack reports `binding_mode`, `connect_needed`, and `ready`, and when
something is left the report ends with `next`, the exact commands still to run.
Run the `connect` commands in `next` as `hcpx connect <pack_id> --json`; packs
with `connect_needed: false` (public packs, the bootstrap pack) need nothing. If
a connect needs the user (a browser consent, a device code, a password), stop
and hand over the exact command. Do not try to obtain or paste credentials
yourself.

## 6. Verify

1. `hcpx commands --json` lists every activated pack with its commands and
   arguments, and every pack you activated must appear.
2. `hcpx availability --json`: packs that need a login are connected.
3. Read the Skill of one pack: `hcpx skill <pack_id> --json`.
4. Run one read command from `hcpx commands`, using the `run` line it prints
   with real values: `hcpx exec <pack_id> <command> --json -- key=value`.
   Expect `"ok": true`.

If a command fails, the result has `code`, `hint`, and often `next`; follow
them. Do not run write commands during setup, and never pass `confirm=true` on
your own.

Access (what runs without asking) belongs to the user, so do not run
`hcpx mode`, `allow`, `ask`, `deny`, `rules rm`, `approve`, or `reject`. They
answer `human_only` when the shell is marked as an agent's (`HCP_AGENT=1`),
which `hcpx adopt claude` sets in `.claude/settings.json` and the Codex block
sets for Codex. Read the current mode with `hcpx access --json` and say in your report
that the user can choose `hcpx mode manual`, `auto` (default), or `run`.

## 7. Report

Tell the user briefly which host you adopted, which packs are active, which
files you wrote or changed (the `written` list of each adopt result), and
anything left for them (approve the MCP server, restart the host, run
`hcpx connect`, install the CLI, pick an access mode).