Subzero agent MCP adapter

Dependency-free Node 20+ stdio adapter for Hermes, OpenClaw, and other MCP clients. Install it with npm i -g @sub-zero/agent-mcp and start it with subzero-agent-mcp, or run it without installing through npx @sub-zero/agent-mcp. A checkout still works: node /absolute/path/to/server.mjs. It connects to the new /agent-api routes, independently of the incident SDK's planned /v2 API.

Create an agent in Subzero → Agents, select projects and permissions, then save its one-time credential in your runtime's secret configuration:

SUBZERO_API_URL=https://your-subzero-api.example.com
SUBZERO_AGENT_TOKEN=<credential from Subzero>

Configure a stdio MCP server using that command and environment. Hermes uses mcp_servers in its configuration; OpenClaw supports MCP configuration in plugin bundles. Follow the installed client's documentation for secret storage. Do not commit credentials. Setup references: Hermes MCP, OpenClaw bundles. Specific client versions have not been exercised in this workspace.

Example Hermes configuration (replace the paths and API URL; inject the token through the process environment):

mcp_servers:
  subzero:
    command: npx
    args: ['@sub-zero/agent-mcp']
    env:
      SUBZERO_API_URL: https://your-subzero-api.example.com

For OpenClaw, a bundle's .mcp.json can declare the same stdio server:

{"mcpServers":{"subzero":{"command":"npx","args":["@sub-zero/agent-mcp"],"env":{"SUBZERO_API_URL":"https://your-subzero-api.example.com"}}}}

The child process must inherit SUBZERO_AGENT_TOKEN. Verify with connection_status before assigning tickets. Use an explicit secret environment entry if your runtime does not inherit it.

Configure a recurring workflow in your runtime:

1. Poll list_assignments; paginate using the returned cursor as after. If your owner enabled self-assignment, also poll list_available and take_ticket one of those codes; without that capability take_ticket is refused and a person has to assign the ticket to you.
2. claim_assignment (renew after ten minutes if still working).
3. get_ticket; use the returned version for mutations.
4. Add an internal note, reply, or resolve with a unique idempotencyKey.
5. Poll get_action_status. Assisted replies/resolutions wait for a human in Subzero. Read the ticket again after each completed action.
6. Stop on access errors or human takeover. Unknown delivery requires human review; do not create another reply to retry it.

The adapter does not run a scheduler or model. Observer agents can only read and can never take work. Support agents act only on tickets assigned to them, whether a person assigned it or they took it themselves. A ticket a person owns, and one a person has taken back from an agent, cannot be taken. Both support modes can add internal notes; assisted mode requires approval for mail and resolution. Resolution records an internal explanation and updates status; it does not automatically send a customer notification. Send and confirm a reply first when notification is needed.

Run npm test in this directory. Implements newline-delimited stdio JSON-RPC with initialization, ping, tool discovery, and tool calls. Supported protocol revisions: 2024-11-05, 2025-06-18, 2025-11-25. Transport reference: MCP specification.