---
title: "§12 Projections"
description: "Normative rules for how a pack appears on other surfaces: CLI grammar, the two host tool shapes, the four-faces rule, and export to MCP or A2UI."
canonical: https://harnesscontextprotocol.io/docs/specification/projections
---

# §12 Projections

> Normative rules for how a pack appears on other surfaces: CLI grammar, the two host tool shapes, the four-faces rule, and export to MCP or A2UI.

A projection is a view of a pack on some surface. Projections MUST NOT add,
remove, or alter Policy, Binding, or Principal semantics, and MUST NOT add
commands the pack does not declare.

## 12.1 CLI

1. A pack's CLI face SHOULD follow `<bin> <space> [<sub…>] [--flags] [--json]`.
2. Every command SHOULD emit structured output when `--json` is present and MUST
   exit non-zero on failure.
3. Health and Binding commands (`doctor`, `status`, `login`, `connect`,
   `whoami`) SHOULD be first-class spaces, not flags on other commands.
4. Verbs SHOULD be `read` by default; `--apply` / `--confirm` SHOULD mark a
   write.
5. Selectors (`--entity`, `--account`, `--pool`) MUST refine within the
   Principal's resolved scope; they MUST NOT select tenant (§9.2).
6. A CLI face MUST NOT prompt interactively when invoked by an agent.
7. `doctor` and `status` SHOULD exit `0` when healthy, `2` on a warning, and `1`
   on failure.
8. A CLI with an installer SHOULD expose it as the family `setup.status`
   (`read`, idempotent: what is installed and linked), `setup.apply` (`write`;
   runs without prompts for an agent Invoker), and `setup.update` (`write`;
   refreshes the Skill after a pack upgrade).
9. Health commands are `read` and MUST NOT mint long-lived credentials.

## 12.2 Host tools

A host projects packs into a tool-calling model in one of two shapes.

1. A host whose agent can run shell commands SHOULD expose a single tool, or the
   runtime's binary itself (`hcpx` in the reference), that forwards argv to a
   runtime (`hcpx exec <pack_id> <verb_key> -- k=v …`), together with a Skill
   that teaches it. Activating a pack
   MUST NOT require the host to register additional tools.
2. A host that runs an in-process tool loop MAY instead expose one tool per
   executable command. Such tools SHOULD be named
   `<pack_id>__<verb_key_with_dots_as_underscores>` (for example
   `mail__mail_list`).
3. A host SHOULD expose `hcp__read_skill` (or equivalent) returning the full
   Skill for a pack, so that the system prompt may carry only leads (§5.3).
4. Tool descriptions SHOULD carry `operation`, `land`, and `confirm` so that the
   model can distinguish reads from writes.
5. A host MUST route every tool call through a runtime that implements §6.3. A
   host MUST NOT execute `wrap.bin` itself.
6. A host MUST filter the projected tool set by the Principal's grants.

## 12.3 Generated surfaces

*Informative.* The reference `hcpx generate` produces, from activated packs:
a stable system-prompt block, a tool list per §12.2, a set of Skill copies, and
each host's own configuration (an MCP server entry, a plugin file, or in-process
tool definitions). `hcpx adopt <host> --write` writes them where that host
reads its configuration.

## 12.4 Four faces

The same command MUST be nameable consistently on four faces:

| Face | Form |
|------|------|
| Wire | `verb_key` (`plan`) |
| CLI | `cli[]` (`transit plan {{from}} {{to}}`) |
| Host tool | `hcpx exec transit plan`, or `transit__plan` in-process |
| Skill | Hot-path table row `plan` |

1. Runtimes SHOULD lint drift among these faces.
2. Renaming a command on one face without the others is a breaking change (§13).

## 12.5 Export to other protocols

1. A runtime MAY export a pack's commands as MCP tools, A2UI components, OpenAPI
   operations, or any other surface. The reference MCP export is a single tool
   named `hcp` (§12.2.1).
2. An export MUST preserve the pack as the unit: one pack → one exported group.
3. An export MUST route invocations back through a runtime that implements
   §6.3; an export MUST NOT reimplement Policy or Binding.
4. An export MUST NOT be the install unit. Installing the export MUST NOT
   substitute for installing the pack.
5. Sense MUST NOT be exported as a tool the model can call to "poll".

## 12.6 What a projection may drop

A projection MAY omit commands the Principal cannot execute and MAY omit the
`hcp` protocol metadata. A projection MUST NOT omit `confirm` markers on
gated writes.

## 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)