hcom-mcp

Control-plane MCP server for launching and supervising hcom-managed agents.

Why HTTP, not stdio

MCP servers typically run over stdio — the client spawns one server process per session. For a control-plane server that manages a fleet of agents, that's a problem: ten terminal sessions spawn ten isolated MCP processes with no coordination between them.

hcom-mcp runs as a single persistent HTTP server. Every terminal session, every MCP client, every agent talks to the same endpoint. One process, one source of truth for launches, registries, and lifecycle.

Related MCP server: GRACE Orchestrator MCP

Prerequisites

• Node.js 22+

• hcom CLI installed and on PATH

Install

git clone https://github.com/scchearn/hcom-mcp.git
cd hcom-mcp
npm install
npm run build

Run

Foreground (any OS)

HCOM_MCP_PORT=3111 node dist/index.js

Listens on http://127.0.0.1:3111/mcp. Only localhost connections are accepted.

As a daemon

Adjust the ExecStart/ProgramArguments path in the config to match where you cloned the repo.

MCP client configuration

Point any HTTP-capable MCP client at http://127.0.0.1:3111/mcp. Example for Claude Desktop:

{
  "mcpServers": {
    "hcom-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3111/mcp"
    }
  }
}

Configuration

• HCOM_MCP_PORT — HTTP port (default: 3111)

• ~/.hcom/mcp/config.json — presets, topologies, model catalogs, rescue allowlist

• ~/.hcom/mcp/registry.json — managed agent registry

• .hcom-mcp.json — optional workspace overlay (see .hcom-mcp.example.json)

Rescue allowlist

unblock and spawn_and_verify only inject input into a blocked agent when the pending launch_blocked detail matches a pattern in rescueAllowlist. Defaults cover the known rescuable dialogs (workspace trust, permission mode, model/provider picker); add patterns for new dialogs without a code release:

{
  "rescueAllowlist": {
    "enabled": true,
    "patterns": ["trust this folder", "permission mode"]
  }
}

Workspace overlays extend the global patterns; they cannot remove the built-in defaults.

Skills

Install with:

npx skills add scchearn/hcom-mcp

Operating guidance ships in skills/:

• skills/using-hcom/SKILL.md — messaging, threads, transcripts, event watching

• skills/hcom-agent-messaging/SKILL.md — agent-to-agent messaging patterns and gotchas

Tools

License

MIT