# Reported issues for Huly MCP

Pod holds 15 of 15 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Huly MCP](/mcp/huly-mcp).

## Most discussed

### list_comments crashes with 'Connection error' when issue has MarkupContent-object comments

## Bug

`list_comments` returns `Connection error while communicating with Huly` when an issue has comments whose `message` field is a `MarkupContent` object (rather than a ProseMirror JSON string).

### Root cause

`optionalMarkupToMarkdown` (in `dist/index.cjs`) assumes `markup` is always a string:

```js
function optionalMarkupToMarkdown(markup, urls, fallback = "") {
  return markup === null || markup === void 0 ? fallback : markupToMarkdownString(markup, urls);
}
```

`markupToMarkdownStrin

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/238) · 2026-08-27 · closed · external user · 3 comments

### update_issue: raw markdown breaks Huly issue description editor

## Problem

Same root cause as [#79](https://github.com/dearlordylord/huly-mcp/issues/79). When editing issues via `update_issue`, Huly browse URLs in markdown descriptions get converted to internal `reference` nodes instead of staying as normal markdown links.

### Symptoms

1. Markdown hyperlinks `[text](huly-url)` appear as plain text or get stripped in the Huly UI
2. Content appears mangled after edit even though it's stored correctly in the DB

### Root Cause

Same as PR [#82](https://githu

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/151) · 2026-06-28 · closed · external user · 2 comments

### create_card cannot create cards of derived (child) master tags — only top-level types

### Summary

  `create_card` rejects any master tag that is a *derived* type (a child extending another master tag), even
  though such cards can be created normally in the Huly UI and the type is a fully registered workspace class.
  Only top-level master tags are accepted.

  ### Environment

  - `@firfi/huly-mcp` **0.21.1**
  - Self-hosted Huly, stdio transport
  - Card space with an `Asset` base master tag and 8 children extending it (`Vehicle`, `Cargo`, `Character`,
  `Prop`, `Environment`,

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/86) · 2026-06-07 · closed · external user · 2 comments

### edit_document and create_document: raw markdown breaks Huly collaborative editor

## Problem

When creating or editing documents via MCP, the content is written as raw markdown to the database. Huly's UI reads documents from a **collaborative document** (via the collaborator service) using **ProseMirror JSON** format. Without calling `uploadMarkup` through the collaborator service, the collaborative document is never properly initialized.

This mirrors the milestone issue (#17) which was fixed in PR #18 for milestones, but documents haven't received the same treatment.

### S

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/79) · 2026-06-03 · closed · external user · 8 comments

### Anthropic API rejects 24 tools: input_schema uses anyOf/oneOf/allOf at the root

## Summary

When `@firfi/huly-mcp` is used with any Anthropic Claude client that sends all MCP tools in a single Messages API request (e.g. claude.ai web, claude.ai desktop), the request fails with:

```
API Error: 400 tools.N.custom.input_schema: input_schema does not support oneOf, allOf, or anyOf at the top level
```

The Anthropic API requires `input_schema` to have `type: "object"` at the root. Composition keywords (`oneOf` / `allOf` / `anyOf`) are allowed inside properties, but not at the 

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/66) · 2026-05-26 · closed · external user · 2 comments

### create_issue_status: 'findAll failed: Cannot read properties of null' on every call (self-hosted v0.7.353)

## What

Every `create_issue_status` call against my self-hosted Huly v0.7.353 fails with the same null-deref. Read-side tools (`get_project_type`, `list_statuses`, etc.) work fine on the same project type — only the write path crashes.

## Repro

Three argument shapes, all reliable failures:

```jsonc
// 1. Display names
{ "name": "Coming Next", "category": "backlog",
  "projectType": "Tracker Project", "taskType": "Status" }

// 2. IDs
{ "name": "Coming Next", "category": "backlog",
  "project

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/34) · 2026-04-30 · closed · outside contributor · 2 comments

### 0.6.0 dist bundle has VERSION hardcoded as 0.5.4

## Description

The `get_version` tool reports `0.5.4` even after updating to `0.6.0` via npm. The `package.json` correctly says `0.6.0`, but the built dist has the old version baked in.

**`dist/index.cjs` line 171239:**
```js
var VERSION = true ? "0.5.4" : "0.0.0-dev";
```

## Root cause

`changeset publish` (used by the `local-release` script) skips npm lifecycle scripts, so the `prepublishOnly` hook never runs. That means `pnpm build` and `pnpm verify-version` are skipped, and the stale dist

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/19) · 2026-04-11 · closed · outside contributor · 1 comment

### [Bug]: `npx` execution fails with `EUNSUPPORTEDPROTOCOL` due to unresolved `workspace:` dependencies

### Description
When attempting to run the package via `npx`, the execution immediately fails because npm encounters an unresolved `workspace:` protocol in the dependency tree.

It appears that `@firfi/huly-mcp` (or its `@hcengineering/*` dependencies) was published to the public npm registry without replacing the monorepo `workspace:` protocols with actual semantic version numbers in the published `package.json`.

### Steps to Reproduce
Run the following command in any standard npm environment:

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/9) · 2026-03-27 · closed · external user · 5 comments

## Most recent

### Expose canonical workbench URL on organization and person responses

## Summary

Document responses include a `url` field pointing at the workbench (`/document/<slug>-<id>`), which makes it trivial for an MCP client to drop a clickable link into a channel message or another doc. Organization and person responses do not include this field, so the client has to either guess the URL pattern or fall back to plain text.

## Affected tools

- `list_organizations`
- `get_organization`
- `list_persons`

(also any other contact-shaped responses where the entity has a stab

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/38) · 2026-05-08 · closed · outside contributor · 0 comments

### create_event always assigns wrong calendar: getDefaultCalendar uses findOne({}) with no filter

## Description

`create_event` (and `create_recurring_event`) always assign events to the wrong calendar 
when a workspace has more than one calendar object.

## Root cause

In `src/huly/operations/calendar-shared.ts`, the function `getDefaultCalendar` is:

```ts
const getDefaultCalendar = (client) => client.findOne(
  calendar.class.Calendar,
  {}  // no filter — takes the first calendar returned by the DB
);
```

This picks whichever calendar the database returns first, which in practice is th

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/36) · 2026-05-06 · closed · external user · 1 comment

### Milestone descriptions empty in Huly UI — missing uploadMarkup for collaborative document

## Problem

Milestone descriptions created or updated via MCP are not rendered in the Huly UI. The description field appears empty ("Add description...") even though the data is correctly stored in the database.

### Root cause

The Huly UI reads milestone descriptions from a **collaborative document** (via the collaborator service), not from the raw `Markup` field stored in the database.

The Markup ↔ markdown conversion was added in `21fa94e`, but `createDoc`/`updateDoc` only set the raw `Mark

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/17) · 2026-04-05 · closed · outside contributor · 0 comments

### Comments and component descriptions bypass Markup conversion — markdown not rendered

## Problem

Comment operations (`addComment`, `updateComment`) and component description operations (`createComponent`, `updateComponent`) store the body/description as a **raw text string** in the `message`/`description` field, bypassing ProseMirror Markup conversion. This causes markdown formatting (`## headings`, `**bold**`, `` `code` ``, lists, tables, etc.) to render as plain text in the Huly UI.

Issue descriptions work correctly because they use `uploadMarkup(...)` with format `"markdown"

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/15) · 2026-04-05 · closed · outside contributor · 0 comments

### feat: add dueDate and estimation fields to create/update issue

## Description

Currently, `create_issue` and `update_issue` MCP tools do not support setting due dates or time estimations. These fields exist in Huly's data model (`IssueData.dueDate`, `IssueData.estimation`) but are hardcoded to `null` and `0` respectively.

## Requested Change

Expose the following optional parameters in both `CreateIssueParams` and `UpdateIssueParams` schemas:

- **`dueDate`**: Unix timestamp in milliseconds (e.g., `1719792000000` for 2024-07-01), or `null` to clear. Option

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/11) · 2026-03-30 · closed · outside contributor · 0 comments

### Move bundled dependencies to devDependencies to fix npx installation

## Problem

The project bundles all source code into `dist/index.cjs` via esbuild with only `ws` as an external dependency. However, all packages (`@hcengineering/*`, `effect`, `@effect/*`, `@modelcontextprotocol/sdk`, `posthog-node`, etc.) are listed under `dependencies` instead of `devDependencies`.

This means that when end users run `npx -y @firfi/huly-mcp@latest`, npm/pnpm attempts to install the full dependency tree — including `@hcengineering/*` packages whose `latest` versions (0.7.382) 

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/10) · 2026-03-30 · closed · outside contributor · 0 comments

### Claude Code MCP setup: special characters in password + self-hosted troubleshooting

## Problem

Setting up huly-mcp with Claude Code on Windows fails when `HULY_PASSWORD` contains special characters (`*`, `%`, `!`, etc.). Additionally, self-hosted Huly has specific gotchas that aren't documented.

## Environment
- Windows 11, Claude Code CLI
- Self-hosted Huly v0.7.382
- huly-mcp latest

## Issues encountered

### 1. Shell escaping mangles passwords with special characters

Using `claude mcp add` with `-e` flag:
```bash
claude mcp add huly -e HULY_PASSWORD='my*pass%word!' -- no

[Read the thread](https://github.com/dearlordylord/huly-mcp/issues/7) · 2026-03-16 · closed · outside contributor · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/dearlordylord/huly-mcp/issues).