Official MCP server

@hlix/mcp is a local tool server that lets the coding agent already open on your machine read your hlix workspace. Cursor, Claude Code, Codex, or Windsurf can inspect projects, tasks, cycles, comments, and verified review evidence without you copying API requests into prompts. It uses the same typed client and workspace boundary as the hlix CLI.

Configure your client

Your MCP client launches the server itself — there is nothing to install by hand. The version is pinned so a client restart cannot silently upgrade a server holding your workspace credentials.

Cursor

Save as .cursor/mcp.json in the project.

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

Claude Code

Save as .mcp.json in the project and approve the server when prompted.

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

Codex

Add to a trusted project’s .codex/config.toml or your user config.

[mcp_servers.hlix]
command = "npx"
args = ["-y", "@hlix/mcp@0.2.0"]
default_tools_approval_mode = "writes"

Windsurf

Add the entry to ~/.codeium/windsurf/mcp_config.json.

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

Connect a client

1. Authenticate once with the CLI.

   hlix auth login --workspace <workspace-id>

   The server reuses the owner-only credential written by the CLI. Never paste an API key into an MCP config or command argument.

2. Bind the repository by importing it.

   cd /path/to/project
   hlix import .

   hlix init selects the API and workspace but does not create or bind a cloud project. A successful import writes the project ID used for strict project scoping.

3. Use the version-pinned configuration above.

   Restart the client or begin a new agent session, then inspect its MCP server list. A user-level global configuration can omit a local binding and operate across the selected workspace.

4. Run a read-only check.

   Ask the agent to list Hlix projects or read one task. In a bound repository, the server exposes only that project and rejects cross-project IDs.

Current versions reports the same state for all three hlix packages, and names the gate each one still has to pass.

Prerequisites

• Node.js 22.13 or later for the Mastra MCP runtime
• a completed hlix auth login
• a selected workspace
• a successful hlix import in the repository when you want strict project scope

The CLI and TypeScript SDK retain their Node.js 20 floor. Only the MCP server needs Node.js 22.13 or later.

Read-only by default

The default process exposes only these tools:

Tool	Purpose
projects_list	list the bound project, or every workspace project in global mode
projects_get	read one project without escaping a local binding
tasks_list	list tasks within the local binding, optionally by status
tasks_get	read one task after verifying its project
tasks_list_comments	read task comments
tasks_get_review	read verified review evidence
cycles_list	list cycles
cycles_get	read one cycle

Responses are bounded before they enter the model context. Errors expose a stable code, HTTP status, and request ID where available, but not response bodies, request headers, URLs, credentials, or stack traces.

Opt into bounded writes

Set HLIX_MCP_ALLOW_WRITES=1 in the MCP server process environment only after reviewing the client’s tool-approval policy. This adds three non-destructive operations:

• tasks_create
• tasks_add_comment
• cycles_propose

For JSON clients, add an env object to the hlix server entry:

{
  "env": {
    "HLIX_MCP_ALLOW_WRITES": "1"
  }
}

For Codex, add:

[mcp_servers.hlix.env]
HLIX_MCP_ALLOW_WRITES = "1"

The process flag is the enforcement boundary

MCP annotations and client confirmation dialogs help a host decide when to ask, but they are not authorization. Without the exact startup value 1, write tools do not exist. Write mode still cannot directly delete projects, invoke the project-start endpoint, change arbitrary task status, access invoices, upload bundles, read protected files, inspect local paths, or run commands. A cycle proposal is operational: on an active autonomous project it resumes roadmap planning and can lead to task dispatch and execution after the orchestrator accepts it.

Authentication and secrets

The preferred path contains no secret in client configuration:

1. hlix auth login stores the credential in an owner-only file;
2. hlix init stores only the API URL, workspace ID, and optional project ID;
3. the MCP child process reads both and rejects symlinked files or configuration directories, non-regular files, foreign ownership, permissive credential modes, cross-project targets, or workspace/API mismatches.

Automation may supply HLIX_API_KEY and HLIX_WORKSPACE_ID from a secret manager. Keep those values in the process environment, never in tool arguments, prompts, committed MCP configuration, or diagnostic output.

Client notes

Where each client keeps its configuration, and what it does about trust. The launch command itself is in the configuration above — paste it verbatim.

Cursor

Cursor loads project MCP configuration from .cursor/mcp.json; the agent and the CLI share that one project definition.

Scope is per project, so a server added here travels with the repository. Review it before committing.

Claude Code

Claude Code stores team-shared project servers in .mcp.json and asks before trusting a project-scoped server the first time it appears.

That prompt is the trust boundary — a server arriving through a pulled branch does not run until someone approves it.

Codex

Codex uses .codex/config.toml for trusted-project scope, or ~/.codex/config.toml for user scope.

Set default_tools_approval_mode = "writes" to use the server’s read-only annotations: reads run, mutations prompt. That pairs with hlix’s own write gate rather than replacing it.

Windsurf

Windsurf reads its user-level ~/.codeium/windsurf/mcp_config.json — not a project file, so a server added here applies everywhere.

Open MCP settings and enable only the tools you want exposed in Cascade.

Verify and troubleshoot

After restarting the client:

• verify that hlix initializes without writing unexpected text to stdout;
• inspect the tool list and confirm write tools are absent by default;
• list projects and compare the workspace with hlix projects list --json;
• if the server reports no credential, rerun login from the project root; if it reports no project, import the repository or supply an explicit project ID in global mode;
• if the process exits immediately, confirm Node.js 22.13 or later and use the exact version shown by the release status.

See Troubleshooting for exact failure modes. To import a third-party MCP definition into a cloud project instead, use Skills, agents & MCP; that is a separate inbound resource flow.

Source references

• Cursor MCP configuration
• Claude Code MCP configuration
• Codex MCP configuration
• Cascade MCP configuration
• MCP Registry publishing

Next steps

Current versionsThe published state of `@hlix/mcp`, and the Registry gate it still has to pass.

Import skills, agents & MCPThe inbound direction — activating a third-party MCP server inside a cloud project.

Reviewing outputThe review evidence this server exposes, and what it means.

TroubleshootingExact failure modes for the server and its clients.