# 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.

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 (`.cursor/mcp.json`), Claude Code (`.mcp.json`), and Windsurf (`~/.codeium/windsurf/mcp_config.json`) use:

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

Codex uses `.codex/config.toml` in a trusted project or the user config:

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

Authenticate with `hlix auth login --workspace <workspace-id>`. Run `hlix import .` to create and bind the cloud project; `hlix init` alone does not write a project ID.

[Current versions](/releases/availability/) 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:

```json
{
  "env": {
    "HLIX_MCP_ALLOW_WRITES": "1"
  }
}
```

For Codex, add:

```toml
[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** 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** 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** 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** 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](/reference/troubleshooting/#the-official-mcp-server) for exact failure modes. To import a third-party MCP definition into a cloud project instead, use [Skills, agents & MCP](/cli/resources/); that is a separate inbound resource flow.

## Source references

- [Cursor MCP configuration](https://cursor.com/docs/mcp)
- [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp)
- [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp)
- [Cascade MCP configuration](https://docs.devin.ai/desktop/cascade/mcp)
- [MCP Registry publishing](https://modelcontextprotocol.io/registry/quickstart)

## Next steps

[Current versions](/releases/availability/)
  [Import skills, agents & MCP](/cli/resources/)
  [Reviewing output](/running/review/)
  [Troubleshooting](/reference/troubleshooting/#the-official-mcp-server)