Connect an agent over MCP

This page is command-line only. The desktop wires its own Superintendent to a Works this way already (see ask the Superintendent). What follows is for connecting an agent runtime of your own.

What the bridge is

hm mcp serve starts an MCP server that speaks over standard input and output. Any agent runtime that can launch an MCP server as a local process can use it. The server offers the hm workflow show catalogue as tools, one tool per hm command, generated from the catalogue the binary ships with. There is no second list of tools to fall out of date.

Three properties are worth knowing before you connect anything:

• Every call runs the real command. A tool call starts the same hm binary as a child process, so it passes the same checks and appends the same record as it would from a terminal.
• Every call is recorded. The bridge writes each tool call to the Works' ledger before returning, whether it succeeded or was refused.
• Standard output is the protocol channel. Logging goes to standard error, so nothing a command prints can corrupt the conversation with the runtime.

The bridge does not offer itself: mcp serve and mcp proxy are never tools.

Start the server

hm --works <path-to-your-works> mcp serve --seat <seat>

The command runs until the client disconnects. The flags that matter:

• --works names the Works the tools act on. Without it, HM_WORKS is used.
• --seat names the seat the agent acts as. hm pins that seat on every command the bridge runs, so a ticket the agent completes is attributed to that seat. Without it, the seat in the environment is used.
• --class-gate holds write and dispatch tools until you approve them. Read tools still run straight away. Use it for an agent you want to review, and leave it off for a hand you have already dispatched.

Register it with your runtime

Agent runtimes differ in where they keep their server list, but most read an mcpServers entry of this shape. Put the full path to the bundled binary in command:

{"mcpServers": {"hm": {
  "command": "/Applications/hm.app/Contents/MacOS/hm",
  "args": ["--works", "<path-to-your-works>", "mcp", "serve", "--seat", "<seat>"]
}}}

A runtime launched from the Dock or Finder does not inherit your shell's PATH, so a bare hm in command is often not found. The full path avoids that.

Calling a tool

Each tool takes the same inputs:

• args for the command's positional arguments, such as a ticket id;
• options for its flags, by name;
• stdin for text the command reads from standard input. Some commands, such as writing a ticket note, accept their body only this way and refuse it as an argument.

A tool's result is the command's output. Commands that support --json return structured results that are easier for an agent to read than the printed text.

Before you connect

Check the seat and its wiring first. hm mcp inspect --seat <seat> reports the MCP servers a seat declares and whether hm holds working keys for each. It shows presence and a short fingerprint, never a key's value. Then run doctor on the Works. While doctor reports a blocking error, the Superintendent's bridge offers a narrower set of tools, and dispatch and land are among those withheld.

For how seats and hands relate, see seats, hands and lines.