FAQ

Each answer here is short and links to the page that owns the topic. Where an answer simplifies, the Specification governs.

Positioning#

Is HCP a replacement for MCP?#

No. MCP is a transport between a model and tools, and HCP is a harness's install unit: one pack carrying Execute, Sense, Policy and Binding (Landscape). A runtime can export a single MCP tool, hcp, that forwards CLI argv, but that tool is a projection (§12.5) and the pack stays the unit you install and authorise.

Is HCP a replacement for Agent Skills?#

No. HARNESS.md follows Agent Skills principles and is copied to SKILL.md on activate. HCP adds what a Skill alone cannot carry: the commands a runtime can execute, the effect class of each and the credential path (Skill).

Why not just ship a CLI and a README?#

A README does not tell a runtime which commands write, which need a credential or which need confirmation. policy.json does, and the runtime enforces it before anything runs (What is HCP).

Is HCP vendor-neutral?#

Yes. The specification names no products (Governance), and hosts and runtimes appear as examples only in Adopt in hosts.

Packs#

What is the smallest valid pack?#

Three files: surface.json with one command, policy.json with one entry for it, and HARNESS.md. The echo gold pack in Examples is exactly that.

Can a pack have no commands?#

Only a sense_only pack can. It must declare at least one trigger (§7.9).

Where do secrets go?#

Never in the pack. A pack declares a Binding mode, and the runtime's hub mints a credential at exec time (§8).

Why is it called surface.json and verb_key if the concept is "command"?#

Wire names are frozen for HCP/1.x compatibility, so the docs say "command" while the wire field stays verb_key (Command). The Roadmap reserves the rename for HCP/2.0.

Do I need --json?#

By default the runtime appends --json to every wrap invocation, so emit JSON when you see it. A CLI that already emits JSON can ignore the flag or set json_flag (CLI projection).

What is a "gated write"?#

It is a command with operation: write and confirm: true, which runs only when args.confirm or args.apply is true. Pack classes shows where it fits.

How do I find existing packs?#

Search the catalog or run hcpx search. Gold packs also scaffold from the CLI (hcpx init transit --template transit).

How do I publish a pack?#

Lint it, then add a row to content/catalog/packs.json or let hcpx share print one (Share a pack). A signed registry belongs to HCP/2.0.

Runtimes#

Must I use the reference SDK?#

No. Any implementation that satisfies §14.3 conforms, and the TypeScript SDK is one (Build runtimes).

What does the runtime enforce that the pack cannot?#

The runtime decides who the Principal is, which tenant and project they act in, which of the five capabilities they hold, whether the confirm gate was satisfied, which credential is minted and whether the binary is allow-listed. Authorization covers the checks.

Can a runtime be proprietary?#

Yes. The pack format is open, and the runtime's hub, store, sink, RBAC tables and isolation are its own (Proprietary runtimes).

What is native-local?#

It is an explicit opt-out of the sandbox jail for a trusted personal machine, set with two flags, sandbox: false and nativeLocal: true. Everything else still applies (§10.3).

Sense#

Is Sense just webhooks?#

No. Sense is the declaration that a pack can announce events, and webhooks, queues and push mappings are only how a runtime receives them (§7.6).

Can a trigger run a command?#

No. A trigger only records, and an Invoker may then choose to Execute under its own grants (§7.2).

Can I poll instead?#

Yes, with a read command. Polling is Execute, so do not declare a trigger for it (Design principles).

Hosts#

How does an agent see a pack?#

A coding agent sees one tool, hcp, and a Skill that teaches it, and hcpx skill <id> prints any pack's HARNESS.md. An in-process loop sees one tool per executable command, named <pack_id>__<verb_key>, a short lead per pack in the system prompt, and an hcp__read_skill tool for the full Skill (Context optimization).

Does the host spawn the binary?#

No. The host calls a runtime, which runs the pipeline and spawns the binary (§12.2).

Project#

What version is this?#

HCP/1.1, still a draft. Versioning explains the scheme.

How do I propose a change?#

Open an issue titled RFC idea: <title> on hcp-protocol to test interest. The RFC process takes it from there.

Where is the source?#

hcp-protocol holds the spec, RFCs and conformance, hcp the SDK, CLI and gold packs, and hcp-docs this site. Governance lists them with their licences.