@hlix/mcp

@hlix/mcp

The official Hlix Model Context Protocol server. It exposes a deliberately bounded set of project, task, cycle, comment, and review tools through the same authenticated @hlix/sdk used by the CLI.

Node.js 22.13 or newer is required by Mastra's MCP runtime. The Hlix CLI and SDK retain their Node.js 20 floor.

MCP clients launch the server themselves — see the configuration below. There is nothing to install by hand.

Authentication

Run the normal CLI setup once:

hlix auth login --workspace <workspace-id>
hlix import .

When an MCP client launches the server from that project, it reuses the owner-only CLI credential and imported .hlix/config.json project binding. The MCP configuration contains no API key.

For CI or a global MCP configuration, set HLIX_API_KEY and HLIX_WORKSPACE_ID. HLIX_BASE_URL and HLIX_PROJECT_ID are optional.

Client configuration

{
  "mcpServers": {
    "hlix": {
      "command": "npx",
      "args": ["-y", "@hlix/mcp@0.2.0"]
    }
  }
}

Cursor stores project configuration in .cursor/mcp.json. Claude Code can use the repository-level .mcp.json. Restart the client or begin a new agent session after adding the server.

Safety boundary

The default server is read-only. It can list and read projects, tasks, cycles, comments, and verified review evidence.

To expose the bounded additive tools that create tasks, add comments, and propose cycles, opt in when the server process starts:

{
  "mcpServers": {
    "hlix": {
      "command": "npx",
      "args": ["-y", "@hlix/mcp@0.2.0"],
      "env": {
        "HLIX_MCP_ALLOW_WRITES": "1"
      }
    }
  }
}

Tool annotations and host confirmation dialogs are advisory. The startup flag is the enforcement boundary: without the exact value 1, mutation tools do not exist. Even in write mode, the server does not expose project deletion, the project-start endpoint, invoice actions, arbitrary task-status mutation, bundle import, protected files, local paths, or command execution. Proposing a cycle to an active autonomous project can resume planning and lead to task dispatch.