---
title: "Quickstart"
description: "Hand setup to your agent or install the CLI yourself, then follow the path for what you build until a read runs and an unconfirmed write is refused."
canonical: https://harnesscontextprotocol.io/docs/quickstart
---

# Quickstart

> Hand setup to your agent or install the CLI yourself, then follow the path for what you build until a read runs and an unconfirmed write is refused.

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.

<AgentPrompts />

| Runbook | Steps | Stops for you when |
|---------|-------|--------------------|
| [`/setup.md`](/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`](/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`](/.well-known/agent-skills/index.json)
and at the top of [`/llms.txt`](/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:

```bash
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:

```bash
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:

```text title="~/.npmrc"
@harnesscontextprotocol:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```

```bash
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](/docs/packs/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](/docs/packs).

```bash
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](/docs/runtimes).

```bash
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](/docs/hosts).

```bash
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](/docs/packs/check#testing)).

```text
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
```

## Sitemap

- [Documentation](https://harnesscontextprotocol.io/docs)
- [Packs](https://harnesscontextprotocol.io/packs)
- [Glossary](https://harnesscontextprotocol.io/docs/reference/glossary)
- [llms.txt](https://harnesscontextprotocol.io/llms.txt)
- [llms-full.txt](https://harnesscontextprotocol.io/llms-full.txt)
- [OpenAPI](https://harnesscontextprotocol.io/openapi.json)
- [MCP](https://harnesscontextprotocol.io/mcp)