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: agentloop

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

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

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

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