Quickstart

Every path starts with the HCP CLI, hcpx, and ends at the same proof: a read that runs and a write that refuses without confirmation. Letting your agent do the setup is fastest; otherwise install the CLI and take the path for what you build.

Let your agent do it#

Two runbooks on this site are written for an agent to follow from start to finish. Give Claude Code, Cursor or Codex the prompt and review what it reports.

Set up HCP in this repo

Set up HCP in this repository. Follow https://harnesscontextprotocol.io/setup.md exactly and report what you changed.

Installs the CLI, activates packs, adopts into the agent you are using, and verifies with a read. Read the runbook

Turn a CLI into a pack

Wrap the `<your-cli>` command as an HCP pack. Follow https://harnesscontextprotocol.io/wrap.md exactly and show me the proof.

Checks the CLI is agent-ready, names its commands, writes Policy and the Skill, lints, and proves it. Read the runbook

Runbook	Steps	Stops for you when
`/setup.md`	Checks `hcpx doctor` and installs the CLI if needed, finds and activates packs, runs the right `hcpx adopt` for its own host, checks availability, runs one read	The CLI cannot be installed, a pack needs a login, or a config outside the repository has to change
`/wrap.md`	Reads the CLI's help to check it is agent-ready, scaffolds with `hcpx wrap`, names 5 to 12 commands, writes Policy and the Skill, lints until clean, installs, proves a read and a refused write	The CLI has no JSON output or only an interactive wizard, or it administers infrastructure (a control-plane pack needs your decision)

Both forbid putting a credential in any file, registering a tool per pack, and running a write with confirm=true you did not approve in the conversation. The runtime enforces those rules too, so an agent that misreads a runbook still cannot spend, send or delete on its own.

Agents that look for skills find both without a prompt, as hcp-setup and hcp-wrap in /.well-known/agent-skills/index.json and at the top of /llms.txt. To keep them in a project, save them as Skills, under .cursor/skills/ for Cursor, or reference the two files from AGENTS.md for Codex:

Terminal

HCP_DOCS=https://harnesscontextprotocol.io   # the origin you are reading
mkdir -p .claude/skills/hcp-setup .claude/skills/hcp-wrap
curl -s "$HCP_DOCS/setup.md" > .claude/skills/hcp-setup/SKILL.md
curl -s "$HCP_DOCS/wrap.md"  > .claude/skills/hcp-wrap/SKILL.md

Install the CLI#

hcpx is itself the first pack. The packages are a private preview on GitHub Packages, so run it from the SDK repository:

Terminal

git clone https://github.com/harnesscontextprotocol/hcp
cd hcp && bun install
alias hcpx="bun $PWD/packages/cli/src/hcp.ts"
hcpx doctor --json

A host starts the CLI from PATH, which an alias does not reach, so put the package on PATH before you adopt a host; hcpx adopt says so when it cannot find the CLI there. With preview access, install from GitHub Packages instead, where GITHUB_TOKEN can read packages and a global install reads the .npmrc in your home directory:

~/.npmrc

@harnesscontextprotocol:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Terminal

bun add -g @harnesscontextprotocol/cli
hcpx doctor --json

The first run creates $HCP_HOME (default ~/.hcp) and installs the hcp-cli bootstrap pack, so there is always something to exec against. Set HCP_HOME to keep a CI or project store apart from your personal one.

JSON

{ "ok": true, "cli": "hcpx", "protocol": "hcp", "version": 1, "home": "~/.hcp", "sandbox_default": true, "installed_count": 1, "activated": [], "connected": [], "bootstrap": "hcp-cli" }

One binary, two names#

@harnesscontextprotocol/cli installs one binary as both hcpx and hcp, which behave the same wherever hcp is this CLI. Everything the CLI prints uses hcpx, because an unrelated tool also installs a command called hcp and may start instead on a machine with both. Hosts still see hcp: one MCP server and one tool of that name, started as hcpx mcp. hcpx adopt writes hcpx into host config, or hcp for an older install that only answers to that name, and allow lists and the sandbox accept both.

Pick your path#

Every path uses the two gold packs in examples/packs/, transit (public read) and ledger (gated write), which are also the conformance suite's fixtures; Examples shows what each proves.

Build a pack#

You ship a CLI or an API and want agents, people and UIs to run it as one governed command. Scaffold from a template, or run hcpx wrap <bin> for a binary already on your PATH, and continue in Build packs.

Terminal

hcpx init weather --class public-read

Implement a runtime#

You build the product that loads packs, enforces grants, mints credentials and executes. Add the reference packages with the .npmrc above and continue in Build runtimes.

Terminal

bun add @harnesscontextprotocol/runtime
bun add @harnesscontextprotocol/sdk

Adopt in a host#

You make an agent product and want it to install packs as easily as it adds an MCP server. Activate packs, generate your host's config and continue in Adopt in hosts.

Terminal

hcpx activate transit ledger
hcpx adopt claude --write        # or: codex, cursor, opencode, grok, mcp, agent

What done looks like#

Every path ends when this proof passes, and a pack runs the same proof in CI to show conformance (Testing).

lint                                  → no issues
one Execute read                      → { ok: true, result: … }
one gated write without confirm       → { ok: false, error: "confirm required" }
the same write with confirm (mock)    → { ok: true }
availability                          → installed · activated · connected · executable