Coding agents

A coding agent with a terminal adopts HCP in one step: hcpx adopt <host> --write puts the protocol Skill, the hcpx binary and one tool named hcp where that host looks for them. The agent then reaches every activated pack through that tool or its shell, so new packs never touch the host's config. The sections below give each host's command and files, and what sets it apart.

What every host shares#

Activate packs, then run your host's adopt target. Add --json and leave out --write to preview the files first.

hcpx activate transit ledger
hcpx adopt <host> --write

Every target writes .hcp/plugin.json, the agent plugin manifest the other files come from, and .hcp/surface.json, the catalog, which adds no tools. Claude Code, Cursor, Codex and Grok Bot also get one MCP server, hcp, that wraps the same bash (hcpx mcp) and starts the CLI by the name that works on your machine; OpenCode gets one plugin tool instead. The tool and the shell reach the same runtime with the same Policy, Binding and sandbox.

The protocol Skill teaches lint, install and exec, and points the agent at each pack's own teaching with hcpx skill <id>. A session looks like this:

hcpx list --json
hcpx skill ledger --json
hcpx exec transit plan --json -- from=Central to=Harbour
hcpx exec ledger transfer --json -- amount=2.80 payee=demo-transit
# { "ok": false, "error": "confirm required" }
hcpx exec ledger transfer --json -- amount=2.80 payee=demo-transit confirm=true

The runtime enforces Policy before the adapter runs, and the Skill tells the agent to ask you and retry with confirm=true only after you agree. The runtime's hub mints credentials at exec time, so no token appears in the conversation, the Skill or the MCP config. Claude Code and Codex also set HCP_AGENT=1 in the agent's shell, so the human-only access commands refuse there (Access).

Claude Code#

hcpx adopt claude --write

To register the server by hand instead of through .mcp.json:

claude mcp add hcp -- hcpx mcp

Cursor#

Cursor discovers the Skill in .cursor/skills/hcp/ with no HCP-specific code.

hcpx adopt cursor --write

{
  "hcp": {
    "enabled": true,
    "home": "/home/you/.hcp",
    "activated": ["transit", "ledger"],
    "sandbox": "sandbox",
    "cli": "hcpx"
  }
}

Codex#

hcpx adopt codex --write

This writes the protocol Skill to .hcp/skills/hcp/SKILL.md, adds one HCP section to AGENTS.md (once, however often you run it) and prints the block for your user config. The CLI never edits files outside the repository, so you add the block yourself:

[mcp_servers.hcp]
command = "hcpx"
args = ["mcp"]

[mcp_servers.hcp.env]
HCP_HOME = "/home/you/.hcp"

# Mark shell commands Codex runs, so hcpx refuses the human-only access commands.
[shell_environment_policy.set]
HCP_AGENT = "1"

HCP_HOME is your store. Because the runtime checks confirm before the adapter runs, the gate holds in every Codex approval mode.

OpenCode#

OpenCode loads HCP as one plugin tool named hcp that runs the CLI without a shell, so adding a pack never adds a tool file.

hcpx adopt opencode --write

{
  "hcp": {
    "enabled": true,
    "home": "~/.hcp",
    "activated": ["transit", "ledger"],
    "sandbox": "sandbox",
    "cli": "hcpx"
  },
  "plugin": ["@harnesscontextprotocol/plugin-opencode"]
}

The plugin is a host shim over wrapHcpArgv. Its one tool takes args or argv as you would type them after the binary (exec transit plan -- from=A to=B) and starts the command in hcp.cli (HCP_CLI overrides it) directly, never through a shell or as a nested mcp. It writes no .opencode/tools/<pack>__<verb>.ts files.

To drive an OpenCode session from your own code, the AI SDK host's HarnessAgent takes runtime: 'opencode'. It maps grant-filtered commands to tools in process, separate from this plugin:

import { Hcp, HarnessAgent } from '@harnesscontextprotocol/sdk'

const hcp = await Hcp.create({ packDirs, sandbox: true })
await hcp.activate(['transit', 'ledger'])

const agent = await HarnessAgent.create({
  hcp,
  runtime: 'opencode',
  cwd: process.cwd(),
  adoptOpenCode: true,
})

Grok Bot#

Grok Bot has a terminal on a persistent Linux computer and Grok Build has a bash tool, so the agent runs hcpx like any other CLI, with MCP as the optional fallback for hosts that only attach connectors.

Grok Bot (cloud computer) / Grok Build (local TUI)
   │  terminal / bash   ← primary
   │  MCP connector     ← optional, one server named hcp
   ▼
hcpx search | install | skill | exec
   ▼
runtime (Policy · Binding · sandbox)

hcpx adopt grok --write      # alias: grokbot

A project .grok/config.toml loads only MCP, plugins and permission, so other Grok settings stay in the user config. Re-running adopt rewrites only the marked block, which is how you change the MCP env or home.

Install the CLI on the Bot's computer, its VM, and put it on PATH like any other CLI the Bot uses. The terminal and the MCP server both run there, so a Bot working on its cloud computer never finds the CLI on your laptop. A first session there runs:

hcpx doctor --json
hcpx search transit --json
hcpx install npm:@harnesscontextprotocol/pack-transit --json
hcpx activate transit --json
hcpx exec transit plan --json -- from=A to=B

Prefer bash, which keeps Policy in the runtime and the tool list the same size as the catalog changes. Use MCP when the host will not let bash run the CLI (a team connector allowlist, a headless attach), and point it at:

[mcp_servers.hcp]
command = "hcpx"
args = ["mcp"]
enabled = true
startup_timeout_sec = 30
env = { HCP_HOME = "~/.hcp" }

tools/list is still [hcp] (MCP export). Grok Bot also follows Cursor MCP policy, with .mcp.json as the shared fragment.

Adding packs later and what to avoid#

hcpx install ./packs/weather --json
hcpx activate weather --json

The agent sees the new pack on its next call, through the hcp tool or hcpx in its shell, while the MCP config, the tool list and the permission prompts stay the same size however many packs you activate. A pack's teaching lives in its HARNESS.md, which agents read with hcpx skill <id>, so re-run hcpx adopt <host> --write only to refresh the protocol Skill and the session or MCP pointer.

Avoid these in every host:

• Registering an MCP server or tool per pack or command. One hcp server reaches all of them.
• Treating MCP server install as pack install (why).
• Putting a token in the MCP config, .cursor/hcp.json, .grok/config.toml, CLAUDE.md, a rule, a Skill or pack files. Binding mints it.
• Exporting tokens into the agent's environment for packs to use. Binding never falls back to the environment.
• Copying pack setup steps into AGENTS.md or generating a Skill file per pack. hcpx skill <id> is the source.
• Pre-approving writes with confirm=true in a standing instruction, which defeats a gate that exists so you agree to each write.