Skip to content
Skip to content

Open protocol · HCP/1.1 Draft

Harness Context
Protocol

The open standard for installing a CLI into any agent harness. A Harness Pack is three files: named commands, a policy, and a skill. A runtime lints it, authorises it, and runs it.

Skills teach. MCP connects. HCP installs.

Get startedWhat is HCP?Read the specification

Where it sits

Three jobs. Three standards.

Skills, MCP, and HCP do different work. Products that treat them as one layer end up inventing a private connector schema to fill the gap.

SKILL.md

Agent Skills

teach

Prose that tells an agent how to behave, disclosed progressively. A Skill cannot execute anything, grant anything, or hold a secret.

MCP server

MCP

connect

A transport between a model and a tool. Something still has to host, authorise, and run the other end of the cable.

Harness Pack

HCP

install

A CLI becomes an installable unit with named commands, Binding, Policy, Sense, and a Skill. A runtime activates it.

If Skills are the manual and MCP is the cable, HCP is the appliance you plug in: versioned, authorised, and the same command whether a human types it, an agent calls it, or a UI button fires it.

Why it matters

Why packs exist

Without an install layer, teams bury OAuth in environment variables, register tools by hand in every host, and treat the agent’s shell as a different API from the product UI. A pack outlives changes in transport and UI.

Pack authors

Publish one folder. Any harness that speaks HCP can activate it. You do not also ship an MCP server, a separate Skill, and a private connector schema.

Harness builders

Activate packs instead of registering tools by hand. Availability reports installed, activated, connected, and executable per command. Hosts take packs in through generated surfaces or the embedded SDK runtime.

Invokers

Human, agent, API, and UI share the same command, the same Policy, and the same Binding. Writes fail closed. Secrets never live in the pack.

The unit

A pack is three files

There is no connector type to implement and no server to host. Describe an existing CLI, say what it may do, and write one screen that teaches it.

surface.jsonThe manifest

Pack id, adapter kind, Binding mode, and the named commands. Five to twelve of them rather than one catch-all verb.

policy.jsonThe rules

One row per command and per trigger: read or write, which land it may touch, and whether it needs confirmation.

HARNESS.mdThe skill

One screen that teaches the hot path and the anti-patterns. On activate it is copied to SKILL.md, so hosts that already read Agent Skills get progressive disclosure for free.

transit/surface.json
{
  "id": "transit",
  "kind": "wrap",
  "cliBin": "transit",
  "binding": { "mode": "public" },
  "verbs": {
    "plan": {
      "description": "Time-first options.",
      "cli": ["transit", "plan", "{{from}}", "{{to}}"]
    }
  }
}
transit/policy.json
{
  "surface_id": "transit",
  "verbs": {
    "plan": {
      "operation": "read",
      "privacy": { "land": "personal" }
    }
  }
}

The lattice

Two loops, one pack

Inbound execution and outbound observation share one Policy and one Binding, and stay isolated from each other. A pack that senses must not mint.

Inbound

Execute

Named CLI commands with a JSON twin, run under Policy, grants, and a sandbox. The agent activates a pack and calls a command. It never registers a tool by hand or wraps a whole binary.

How execution works

Outbound

Sense

Triggers a pack may announce, declared in the same Policy file. Sense only emits. An observation cannot turn into an action on its own; an Invoker has to run Execute, under its own grants.

How triggers work

Quickstart

Install a pack, run a command

The first run creates $HCP_HOME and installs the hcp-cli bootstrap pack. After that it is install, activate, exec.

$ hcp doctor$ hcp install ./examples/packs/transit$ hcp activate transit$ hcp exec transit plan -- from=A to=B

hcp availability reports installed, activated, connected, and executable for each command under the current grants, so an agent can see what it may run before it tries.

Build your first packGlossary

What you can build

Start from a class, not a blank file

Most packs fall into one of a few shapes. Copy the closest one, change four fields, and lint.

transit

Public read

Five commands, no login, no secrets: find, plan, show, status, follow. Copy this shape for any discovery surface.

Read the guide

ledger

Gated write

Onboard, connect, one domain read, and a transfer that fails closed unless the caller confirms.

Read the guide

sense_only

Sense only

A pack that announces triggers and mints nothing. Observation stays separate from execution.

Read the guide

Adoption

Hosts adopt HCP natively

A harness does not have to bridge through MCP to use packs. The CLI generates native surfaces for a host, and the SDK embeds the runtime directly.

Generate native surfaces

$ hcp adopt cursor --write$ hcp adopt opencode --write

Tool maps, skill leads, and approval prompts for write commands are generated from the activated packs. Nothing is maintained by hand per host.

Embed the runtime

agent.ts
import { Hcp } from '@harnesscontextprotocol/sdk'

const hcp = await Hcp.create({
  packDirs: [`${process.env.HOME}/.hcp/packs/transit`],
  sandbox: true,
})

await hcp.activate(['transit'])

Next

Start building

Build a pack

Copy a gold pack, change four fields, write one policy row per command and one screen of skill. Lint, then exec.

Implement a runtime

Load, authorise, bind, execute, route Sense. Fail closed at every step. Pass the conformance vectors.

Read the specification

Fourteen normative sections in RFC 2119 language. Each MUST has a conformance vector behind it.