huly-mcp

# Huly MCP

[![npm](https://img.shields.io/npm/v/@firfi/huly-mcp)](https://www.npmjs.com/package/@firfi/huly-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@firfi/huly-mcp)](https://www.npmjs.com/package/@firfi/huly-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
[![Glama score](https://glama.ai/mcp/servers/@dearlordylord/huly-mcp/badges/score.svg)](https://glama.ai/mcp/servers/@dearlordylord/huly-mcp)
[![MCP Server](https://badge.mcpx.dev?type=server&features=tools)](https://github.com/dearlordylord/huly-mcp)[![cooked at Monadical](https://img.shields.io/endpoint?url=https://monadical.com/static/api/cooked-at-monadical.json)](https://monadical.com)

**Huly MCP** is a feature-complete MCP server for [Huly](https://huly.io/) integration. Published on npm as [`@firfi/huly-mcp`](https://www.npmjs.com/package/@firfi/huly-mcp).

It connects to Huly Platform deployments and should also work with the [Platform Collective](https://github.com/Platform-Collective/platform) and [TraceX](https://tracex.co) forks. [Intabia](https://platform.intabia.ru/) `0.8.33` / model `0.8.4` has been compatibility-tested; [known gaps are tracked in issue #279](https://github.com/dearlordylord/huly-mcp/issues/279). Fork support remains unofficial.

## Huly CLI Alternative

Looking for a Huly CLI, terminal-native Huly integration, or a scripting and automation alternative to running an MCP server? [Huly CLI](https://huly-mcp.dearlordylord.com/cli/) is a feature-complete command-line interface for Huly, published as [`@firfi/huly-cli`](https://www.npmjs.com/package/@firfi/huly-cli), with full Huly operation parity with Huly MCP. It exposes the same Huly operations as native, schema-aware commands with human-readable or JSON output, file-backed inputs, uploads, and downloads.

Huly MCP and Huly CLI are maintained together in this monorepo and derive from the same shared operation registry, keeping operation inputs, outputs, warnings, and typed failures aligned. See the [Huly CLI documentation](packages/huly-cli/README.md) for the complete generated command reference, or browse [CLI examples](https://huly-mcp.dearlordylord.com/cli/examples/), [Huly automation patterns](https://huly-mcp.dearlordylord.com/cli/automation/), and the [Huly MCP vs CLI comparison](https://huly-mcp.dearlordylord.com/cli/huly-mcp-vs-cli/).

## Installation

### Node.js requirement

Huly MCP requires **Node.js 22.19.0 or later**. MCP clients do not provide a Node.js runtime: `node`, `npx`,
and the `#!/usr/bin/env node` package executable resolve Node.js from the environment in which the MCP client
runs. Check that environment before installation:

```bash
node --version
```

If an MCP client starts Huly MCP with an older runtime, Huly MCP initializes a diagnostic-only MCP surface instead
of loading the incompatible application. Its server instructions and `get_huly_startup_diagnostic` tool report the
detected executable and required version, and the same `unsupported Node.js runtime` diagnostic is written to
stderr. Upgrade Node.js or configure the MCP server command to use the absolute path of a compatible Node.js
executable, then restart the MCP server. Huly operations remain unavailable until the runtime is upgraded.

The standard configuration works with most MCP clients:

```json
{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}
```

## Tool Exposure Defaults

By default (`HULY_TOOL_MODE=auto`), Huly MCP optimizes for current MCP clients by avoiding a 470-tool eager list. Exact `claude-code` sessions receive native Huly tools. Codex, Cursor, Windsurf, Copilot, OpenCode, Claude AI/Desktop-style clients, and unknown clients receive a small proxy surface: `list_tool_categories`, `search_tools`, `get_tool_schema`, and `invoke_tool`.

Exact native tool names still dispatch when a client calls them directly, but many clients only call tools returned by `tools/list`. Set `HULY_TOOL_MODE=native` to make every Huly tool appear first-class, or use `TOOLSETS` / `TOOLS` to pin frequently used native tools while keeping proxy discovery available.

<details>
<summary>Codex</summary>

Use Codex's MCP manager:

```bash
codex mcp add huly \
  --env HULY_URL=https://your-huly-instance.example.com \
  --env HULY_EMAIL=your@email.com \
  --env HULY_PASSWORD=yourpassword \
  --env HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest
```

Or add it directly to `~/.codex/config.toml`:

```toml
[mcp_servers.huly]
command = "npx"
args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env]
HULY_URL = "https://your-huly-instance.example.com"
HULY_EMAIL = "your@email.com"
HULY_PASSWORD = "yourpassword"
HULY_WORKSPACE = "yourworkspace"
```

</details>

<details>
<summary>Claude Code</summary>

```bash
claude mcp add huly \
  -e HULY_URL=https://your-huly-instance.example.com \
  -e HULY_EMAIL=your@email.com \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest
```

Or add to `~/.claude.json` using the standard config above.

</details>

<details>
<summary>Claude Desktop</summary>

Add the standard config to your `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

</details>

<details>
<summary>VS Code</summary>

Add with Command Palette → "MCP: Add Server", or put this in a VS Code MCP config such as `.vscode/mcp.json`. Do not commit workspace config files that contain real credentials.

```json
{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}
```

</details>

<details>
<summary>Cursor</summary>

Add the standard config to `~/.cursor/mcp.json`, or via Settings → Tools & Integrations → New MCP Server.

</details>

<details>
<summary>Windsurf</summary>

Add the standard config to your Windsurf MCP configuration file.

</details>

<details>
<summary>OpenCode</summary>

Open the global configuration file (`~/.config/opencode/opencode.json`) and merge this entry into your config:

```json
{
  "mcp": {
    "huly": {
      "type": "local",
      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}
```

</details>

<details>
<summary>Pi</summary>

Pi requires an MCP adapter. Install it, then use Huly MCP in `auto` mode with the four proxy tools
promoted into Pi's native tool list:

```bash
pi install npm:pi-mcp-adapter
```

See the [Pi setup guide](docs/PI_SETUP.md) for the user-global configuration, optional
`TOOLSETS`/`TOOLS` native pins, and verification steps.

</details>

## Updating

The `@latest` tag asks the package runner for the newest version. Some MCP clients keep server processes or resolved installs alive, so restart or re-add the server when updating:

| Client | How to update |
|--------|--------------|
| **Codex** | `codex mcp remove huly` then re-add with the install command above. If your password has shell-sensitive characters, edit `~/.codex/config.toml` directly instead |
| **Claude Code** | `claude mcp remove huly` then re-add with the install command above |
| **Claude Desktop** | Restart the app (it runs `npx` on startup) |
| **VS Code / Cursor** | Restart the MCP server from the command palette/configured client or reload the window |
| **OpenCode** | Restart OpenCode or start a new session after config changes |
| **Pi** | Run `/mcp reconnect huly`, then `/reload` if the registered direct-tool surface changed |
| **npx (manual)** | `npx -y @firfi/huly-mcp@latest` — the `-y` flag auto-confirms install prompts |

## Maintainer Production Release

Publish from a clean, current `master` checkout with the preferred certified Node.js runtime:

```bash
mise exec node@24.15.0 -- pnpm local-release
```

Use this exact command even when a newer Node.js version is active on the host. The release build accepts only the
exact Node.js versions certified by CI; this is intentionally narrower than the package's runtime requirement. See
the [production release guide](docs/NPM_PRODUCTION_RELEASE.md) for preflight checks, rerun behavior, and verification.

## HTTP Transport

By default, the server uses stdio transport. For HTTP transport:

```bash
HULY_URL=https://your-huly-instance.example.com \
HULY_EMAIL=your@email.com \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/huly-mcp@latest
```

Server listens on `http://127.0.0.1:3000/mcp` by default.

Configure with `MCP_HTTP_PORT` and `MCP_HTTP_HOST`:

```bash
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-mcp@latest
```

### HTTP MCP Protocol Support

Both stdio and HTTP implement the released MCP `2026-07-28` interface and retain SDK-owned compatibility for MCP `2025-06-18` clients. Stdio pins each connection to the protocol era selected by its opening exchange; HTTP serves legacy requests statelessly. Modern HTTP requires one JSON-RPC message per POST, `Accept: application/json, text/event-stream`, `MCP-Protocol-Version: 2026-07-28`, `Mcp-Method`, method-speci