huly-mcp

Huly MCP

      

Huly MCP is a feature-complete MCP server for Huly integration. Published on npm as @firfi/huly-mcp.

[!IMPORTANT] Hosted Huly is shutting down. Huly's upstream README says shutdown is expected July 20. If you use https://huly.app, export and migrate your data as soon as possible. See the backup and restore guide and self-hosting repository. Self-hosted deployments are not affected.

Installation

The standard configuration works with most MCP clients:

{
  "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:

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:

[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>

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.

{
  "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:

{
  "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>

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 | | npx (manual) | npx -y @firfi/huly-mcp@latest — the -y flag auto-confirms install prompts |

HTTP Transport

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

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:

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-specific Mcp-Name, and per-request _meta.io.modelcontextprotocol/ client metadata. Huly credentials are configured separately through env vars or supported x-huly- headers.

For hosted or tunneled HTTP deployments, you can require an MCP endpoint bearer token:

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npx -y @firfi/huly-mcp@latest

HTTP clients must then send:

Authorization: Bearer <MCP_AUTH_TOKEN>

MCP_AUTH_TOKEN protects only the MCP HTTP /mcp endpoint. It is unrelated to HULY_TOKEN, does not authenticate to Huly, and does not replace HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN. Huly credentials are still required through process env vars or, for hosted URL deployments, the supported x-huly-* headers. Stdio deployments do not use MCP_AUTH_TOKEN.

Hosted HTTP Header Configuration

For hosted URL deployments, keep the server process configured with MCP_TRANSPORT=http. A hosting layer can forward per-session Huly credentials as request headers, so one hosted server can serve different Huly workspaces without process-wide HULY_* env vars.

Supported v1 headers:

| Header | Required | Description | |--------|----------|-------------| | x-huly-url | Yes | Huly instance URL | | x-huly-workspace | Yes | Workspace identifier | | x-huly-token | Yes | Huly API token | | x-huly-connection-timeout | No | Connection timeout in ms |

If any x-huly-* header is present, all required headers must be present. Missing values are not filled from environment variables. Email/password auth is not supported in hosted header configuration v1.

For a Smithery publish schema example, see docs/SMITHERY_URL_PUBLISH.md.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | HULY_URL | Yes | Reachable self-hosted or replacement hosted Huly instance URL | | HULY_EMAIL | Auth | Account email | | HULY_PASSWORD | Auth | Account password | | HULY_TOKEN | Auth* | API token (alternative to email/password) | | HULY_WORKSPACE | Yes | Workspace identifier | | HULY_CONNECTION_TIMEOUT | No | Connection timeout in ms. Omit to use the package default. | | MCP_TRANSPORT | No | Transport type: stdio (default) or http | | MCP_HTTP_PORT | No | HTTP server port (falls back to PORT, then 3000) | | MCP_HTTP_HOST | No | HTTP server host. Omit to bind to the package default loopback host. | | MCP_AUTH_TOKEN | No | Optional bearer token required by HTTP clients for /mcp. This protects the MCP endpoint only; it is not a Huly API token. | | HULY_TOOL_MODE | No | Tool exposure mode: auto (default), native, or proxy. auto keeps exact claude-code native and resolves Codex, Cursor, Windsurf, Copilot, opencode, Claude AI, and unknown clients to proxy mode. | | PROXY_OUTPUT_STRICT | No | Proxy candidate strictness: false (default) keeps proxy discovery broad; true makes active TOOLSETS / TOOLS a hard allow-list for proxy search, schema lookup, and invocation. | | TOOLSETS | No | Comma-separated tool categories to expose. If neither TOOLSETS nor TOOLS is set, all native Huly tools are exposed. Example: issues,projects,search | | TOOLS | No | Comma-separated exact tool names to expose in addition to selected toolsets. Example: list_documents,create_issue |

*Auth: Provide either HULY_EMAIL + HULY_PASSWORD or HULY_TOKEN.

Built-in Diagnostic Tools

get_version returns the current server version and latest npm version.

get_huly_context returns sanitized runtime/configuration context for the current MCP session without connecting to Huly. It reports package version, transport, auth mode, sanitized Huly URL origin/host/protocol, workspace, timeout, config sources, native tool scope filtering, and resolved native/proxy tool exposure. Tokens, passwords, email values, credential headers, URL paths, URL query strings, and URL credentials are never returned.

MCP Resources

The server exposes read-only MCP Resources as JSON context for clients that support resources/read.

<!-- resources:start --> <!-- AUTO-GENERATED from src/mcp/resources.ts resourceTemplates. Do not edit manually. Run pnpm update-readme to regenerate. --> | Template | Name | Description | MIME Type | |----------|------|-------------|-----------| | huly://projects/{project} | huly-project | Read full details for a Huly tracker project by project identifier, for example huly://projects/HULY. | application/json | | huly://issues/{issue} | huly-issue | Read full details for a Huly issue by full issue identifier, for example huly://issues/HULY-123. | application/json | | huly://projects/{project}/issues/{issue} | huly-project-issue | Read full details for a Huly issue by project identifier and issue number, for example huly://projects/HULY/issues/123. | application/json | <!-- resources:end -->

resources/list returns concrete active project resources. Issue resources are template-based: use resources/templates/list to discover supported issue URI templates, then read a known issue URI.

Backlog

Feature backlog and SDK parity notes live in docs/BACKLOG.md.

<!-- tools:start --> <!-- AUTO-GENERATED from src/mcp/tools/ descriptions. Do not edit manually. Run pnpm update-readme to regenerate. -->

Available Tools

When resolved tool exposure is proxy, clients see the built-in tools plus these proxy meta-tools. Native Huly tools are then discovered and invoked through the proxy candidate catalog. Exact native tool names also dispatch when a client calls them directly, subject to PROXY_OUTPUT_STRICT scope rules, but hidden native tools are not advertised through tools/list.

Proxy Meta-Tools

| Tool | Description | |------|-------------| | list_tool_categories | Lists Huly tool categories available through this proxy. Use this first when you need a broad map of capabilities before searching for a specific Huly tool. | | search_tools | Searches the current proxy-visible Huly tool catalog by tool name, category, description, and parameter names. Returns exact tool names plus required and optional parameter names for single-call follow-up with get_tool_schema or invoke_tool. | | get_tool_schema | Returns the exact input and output schema for one proxy-visible Huly tool. Use this before invoke_tool when you are not certain about required argument names or result shape. | | invoke_tool | Invokes one proxy-visible Huly tool by exact name with its arguments. This tool can call read or write Huly operations; check get_tool_schema and the target tool annotations when safety matters. |

TOOLSETS categories: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, associations, activity, notifications, workspace, approvals, boards, cards, collaborators, custom-fields, drive, inventory, labels, leads, templates, model-administration, planner, preferences, processes, recruiting, sdk-discovery, security-administration, sequence-administration, spaces, tag-categories, tags, task-management, test-management, user-statuses, views, virtual-office, workflow-statuses

Projects

| Tool | Description | |------|-------------| | list_project_target_preferences | List low-level per-project tracker target preference records. These Huly ProjectTargetPreference records are attached to projects and used by tracker UI/workflows to remember target-related preference props. Omit project to list recent preferences across projects, or pass a project identifier to inspect one project's preference. Props are SDK-open key/value payloads. | | upsert_project_target_preference | Create or update the low-level ProjectTargetPreference record for a project. This refreshes usedOn and merges SDK-open target preference props by key. Use for tracker SDK parity or advanced administration; ordinary project and issue workflows usually do not need this tool. | | list_projects | List all Huly projects. Returns projects sorted by name. Supports filtering by archived status. | | get_project | Get full details of a Huly project including its statuses. Returns project name, description, archived flag, default status, and all available statuses. | | list_statuses | List all issue statuses for a Huly project with workflow category and default info. Returns status name, category, and isDefault. Use this to discover valid statuses before creating or updating issues. | | create_project | Create a new Huly tracker project. Idempotent: returns existing project if one with the same identifier already exists (created=false). Identifier must be 1-5 uppercase alphanumeric chars starting with a letter. | | update_project | Update a Huly project. Only provided fields are modified. Set description to null to clear it. | | delete_project | Permanently delete a Huly project. All issues, milestones, and components in this project will be orphaned. This action cannot be undone. |

Issues

| Tool | Description | |------|-------------| | preview_deletion | Preview the impact of deleting a Huly entity before actually deleting it. Shows affected sub-entities, relations, and warnings. Supports issues, projects, components, and milestones. Use this to understand cascade effects before calling a delete operation. | | list_components | List components in a Huly project. Components organize issues by area/feature. Returns components sorted by modification date (newest first). | | get_component | Retrieve full details for a Huly component. Use this to view component content and metadata. | | create_component | Create a new component in a Huly project. Components help organize issues by area/feature. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Returns the created component ID and label. | | update_component | Update fields on an existing Huly component. Only provided fields are modified. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | set_issue_component | Set or clear the component on a Huly issue. Pass null for component to clear it. | | delete_component | Permanently delete a Huly component. This action cannot be undone. | | list_issues | Query Huly issues with optional filters. Returns issues sorted by modification date (newest first). Supports filtering by project, exact workflow status name (status), Huly SDK task.statusCategory key (statusCategory: UnStarted, ToDo, Active, Won, Lost), assignee, creator (raw Person ID, exact email, or exact display name), component, a human-readable attached label title (label, exact and case-insensitive), milestone (project-scoped ID or exact case-insensitive label), milestone presence (hasMilestone), parentIssue (to list children of a specific issue), and isTopLevel (to return only native top-level issues). Creator, label, and milestone filters are applied before the result limit; ambiguous creator display names fail actionably and unknown creators return an empty list. Each result includes creator as a stable Person reference { id, name?, email? } when resolvable and the assigned milestone as { id, label } when resolvable. Supports searching by title substring (titleSearch) and description content (descriptionSearch). Each result includes deterministic label summaries with title and available color; missing labels are an empty array, duplicate titles collapse case-insensitively while preferring a valid color, and unusable partial attachments are omitted with a tool warning. | | get_issue | Retrieve full details for a Huly issue including markdown description, its creator as a stable Person reference { id, name?, email? } when resolvable, its assigned milestone as { id, label } when resolvable, and deterministic attached-label summaries with title and available color. Missing labels are an empty array, duplicate titles collapse case-insensitively while preferring a valid color, and unusable partial creator or label metadata is omitted with one bounded tool warning. Use this to view issue content, comments, classification, or full metadata. | | create_issue | Create a new issue in a Huly project. Omit parentIssue for a native top-level issue, or specify parentIssue to create a sub-issue. Optionally set taskType by ID or display name; it is resolved within the target project's project type, and status is validated against that task type's workflow. Use list_task_types or get_project_type to discover valid task types and statuses. Description supports markdown formatting; markdown links to current-workspace Huly browse URLs with _class, _id, and label become native references, while external URLs stay normal links. Returns the created issue identifier. | | update_issue | Update fields on an existing Huly issue. Optionally set taskType by ID or display name; it is resolved within the target project's project type, and the status is preserved only when valid for the new task type. Use list_task_types or get_project_type to discover valid task types and statuses. Only provided fields are modified. Description updates support markdown; markdown links to current-workspace Huly browse URLs with _class, _id, and label become native references, while external URLs stay normal links. | | add_issue_label | Add a tag/label to a Huly issue. Creates the tag if it doesn't exist in the project. | | remove_issue_label | Remove a tag/label from a Huly issue. Detaches the label reference; does not delete the label definition. | | delete_issue | Permanently delete a Huly issue. This action cannot be undone. | | move_issue | Move an issue to a new parent (making it a sub-issue), or pass null to restore its native top-level shape. Updates parent/child relationships and sub-issue counts. | | list_issue_templates | List issue templates in a Huly project. Templates define reusable issue configurations. Returns templates sorted by modification date (newest first). | | get_issue_template | Retrieve full details for a Huly issue template including children (sub-task templates). Use this to view template content, default values, and child template IDs. | | create_issue_template | Create a new issue template in a Huly project. Templates define default values for new issues. Template and child descriptions support markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Optionally include children (sub-task templates) that will become sub-issues when creating issues from this template. Returns the created template ID and title. | | create_issue_from_template | Create a new issue from a template. Applies template defaults, allowing overrides for specific fields. Description override supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. If the template has children (sub-task templates), sub-issues are created automatically unless includeChildren is set to false. Returns the created issue identifier and count of children created. | | update_issue_template | Update fields on an existing Huly issue template. Only provided fields are modified. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | delete_issue_template | Permanently delete a Huly issue template. This action cannot be undone. | | add_template_child | Add a child (sub-task) template to an issue template. The child defines default values for sub-issues created when using create_issue_from_template. Child description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Returns the child template ID. | | remove_template_child | Remove a child (sub-task) template from an issue template by its child ID. Get child IDs from get_issue_template response. | | add_issue_relation | Add a relation between two issues. Relation types: 'blocks' (source blocks target — pushes into target's blockedBy), 'is-blocked-by' (source is blocked by target — pushes into source's blockedBy), 'relates-to' (bidirectional link — updates both sides). targetIssue accepts cross-project identifiers like 'OTHER-42'. No-op if the relation already exists. | | remove_issue_relation | Remove a relation between two issues. Mirrors add_issue_relation: 'blocks' pulls from target's blockedBy, 'is-blocked-by' pulls from source's blockedBy, 'relates-to' pulls from both sides. No-op if the relation doesn't exist. | | list_issue_relations | List all relations of an issue. Returns blockedBy (issues blocking this one), blocks (issues this one blocks), relations (bidirectional issue links), and documents (linked documents with title/teamspace). | | link_document_to_issue | Link a Huly document to an issue. The link appears in the issue's Relations panel in the UI. Idempotent: no-op if the document is already linked. Use list_issue_relations to see linked documents. | | unlink_document_from_issue | Remove a document link from an issue. Idempotent: no-op if the document is not linked. | | list_related_issue_targets | List rules that choose the default destination project for related issues. A spaceRule says related issues from one space default to targetProject. A classRule says related issues for one object class default to targetProject. targetProject is a project identifier, or null for no default destination project. | | set_related_issue_target | Set the default destination project for related issues from a space or object class. For space, creates or updates a spaceRule. For objectClass, only updates an existing classRule; this tool never creates classRule targets. Pass targetProject as a project identifier, or null to clear the default destination project. | | delete_related_issue_space_target | Delete the spaceRule that chooses the default destination project for related issues from one space. This only deletes spaceRule targets; classRule deletion is intentionally unsupported because class rules may be model-provided. |

Comments

| Tool | Description | |------|-------------| | list_comments | List comments on a Huly issue. Returns comments sorted by creation date (oldest first). | | add_comment | Add a comment to a Huly issue. Comment body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | update_comment | Update an existing comment on a Huly issue. Comment body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | delete_comment | Delete a comment from a Huly issue. This action cannot be undone. |

Milestones

| Tool | Description | |------|-------------| | list_milestones | List milestones in a Huly project. Returns milestones sorted by modification date (newest first). | | get_milestone | Retrieve full details for a Huly milestone. Use this to view milestone content and metadata. | | create_milestone | Create a new milestone in a Huly project. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Returns the created milestone ID and label. | | update_milestone | Update fields on an existing Huly milestone. Only provided fields are modified. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | set_issue_milestone | Set or clear the milestone on a Huly issue. Pass null for milestone to clear it. | | delete_milestone | Permanently delete a Huly milestone. This action cannot be undone. |

Documents

| Tool | Description | |------|-------------| | list_document_snapshots | List version-history snapshots for one Huly document. A snapshot is a saved point-in-time copy from the document's change history. Resolve the document by teamspace plus document title or ID. Returns snapshotId, documentId, teamspaceId, title, parentDocumentId, and timestamps; markdown content is intentionally omitted. Use get_document_snapshot with snapshotId when reading content. | | get_document_snapshot | Get one point-in-time Huly document history snapshot and return markdown content. Resolve the document by teamspace plus document title or ID; resolve the snapshot by snapshotId, exact snapshot title, or exact createdOn timestamp. Prefer snapshotId from list_document_snapshots when titles or dates may collide. Restore is out of scope. | | list_teamspaces | List all Huly document teamspaces. Returns teamspaces sorted by name. Supports filtering by archived status. | | get_teamspace | Get details for a Huly document teamspace including document count. Finds by name or ID, including archived teamspaces. | | create_teamspace | Create a new Huly document teamspace. Idempotent: returns existing teamspace if one with the same name exists. | | update_teamspace | Update fields on an existing Huly document teamspace. Only provided fields are modified. Set description to null to clear it. | | delete_teamspace | Permanently delete a Huly document teamspace. This action cannot be undone. | | list_documents | List documents in a Huly teamspace. Returns documents sorted by modification date (newest first). Each result includes a 'url' field pointing to the document in the Huly web app. Supports searching by title substring (titleSearch) and content (contentSearch). | | get_document | Retrieve full details for a Huly document including markdown content and a 'url' field pointing to the document in the Huly web app. Use this to view document content and metadata. | | create_document | Create a new document in a Huly teamspace. Content is markdown and supports native Mermaid diagrams (``mermaid blocks render interactively in Huly UI). Use markdown links to current-workspace Huly browse URLs for native references; Huly browse links returned in get_document content round-trip as native references. The URL identifies the object; link text is display text; plain issue keys stay text. External URLs stay normal markdown links. Optionally pass parent as a document title or ID to create a nested child document; invalid parents fail instead of silently creating a top-level document. Returns the created document id and a 'url' field pointing to the document in the Huly web app. Use link_document_to_issue only if you also want an issue-document association. | | edit_document | Edit an existing Huly document. You may rename with title and/or edit the body. Body editing has two mutually exclusive modes: (1) content replaces the entire markdown body, (2) old_text + new_text performs exact targeted search-and-replace. Use markdown links to current-workspace Huly browse URLs for native references; Huly browse links returned in get_document content round-trip as native references. The URL identifies the object; link text is display text; plain issue keys stay text. External URLs stay normal markdown links. For targeted replace, multiple matches error unless replace_all is true; empty new_text deletes matched text. Content supports native Mermaid diagrams. Returns a 'url' field pointing to the document in the Huly web app. | | list_inline_comments | List inline comment threads from a Huly document. Extracts comments embedded in document content as ProseMirror marks. Each comment includes the highlighted text and thread ID. Set includeReplies=true to also fetch thread reply messages with sender names. | | delete_document` | Permanently delete a Huly document. This action cannot be undone. |

Storage

| Tool | Description | |------|-------------| | upload_file | Upload a file to Huly storage. Provide one source: filePath is resolved on the MCP server host, data is client-local base64 content, and fileUrl is fetched by the MCP server. Returns the blob ID and URL. |

Attachments

| Tool | Description | |------|-------------| | list_attachments | List attachments on a Huly object (issue, document, etc.). Returns attachments sorted by modification date (newest first). | | get_attachment | Retrieve full details for a Huly attachment including download URL. | | add_attachment | Add an attachment to a Huly object. Provide one source: filePath is resolved on the MCP server host, data is client-local base64 content, and fileUrl is fetched by the MCP server. Returns the attachment ID and download URL. | | update_attachment | Update attachment metadata (description, pinned status). | | delete_attachment | Permanently delete an attachment. This action cannot be undone. | | pin_attachment | Pin or unpin an attachment. | | download_attachment | Get download URL for an attachment along with file metadata (name, type, size). | | read_attachment_content | Return a supported image attachment (JPEG, PNG, GIF, or WebP; maximum 4 MiB) as one MCP image content block plus metadata-only structured content. Use this to inspect screenshots or pictures directly. For non-image, unsupported, or oversized files, call download_attachment to get a URL instead. | | add_issue_attachment | Add an attachment to a Huly issue resolved by project and identifier. Provide one source: filePath is resolved on the MCP server host, data is client-local base64 content, and fileUrl is fetched by the MCP server. | | add_document_attachment | Add an attachment to a Huly document resolved by teamspace and title/ID. Provide one source: filePath is resolved on the MCP server host, data is client-local base64 content, and fileUrl is fetched by the MCP server. | | save_attachment | Save/bookmark an attachment for later reference. Idempotent when already saved. | | unsave_attachment | Remove an attachment from saved/bookmarks. | | list_saved_attachments | List saved/bookmarked attachments for the current user. | | list_drawings | List drawings attached to a raw Huly parent object. | | get_drawing | Get a drawing by ID. | | create_drawing | Create a drawing under a raw Huly parent object. | | update_drawing | Update drawing content. Pass null content to clear it. | | delete_drawing | Delete a drawing. This action cannot be undone. |

Contacts

| Tool | Description | |------|-------------| | list_persons | List all persons in the Huly workspace. Returns persons sorted by modification date (newest first). Supports searching by name substring (nameSearch) and email substring (emailSearch). | | get_person | Retrieve full details for a person including contact channels. Use personId or email to identify the person. | | create_person | Create a new person in Huly. Returns the created person ID. | | update_person | Update fields on an existing person. Only provided fields are modified. | | delete_person | Permanently delete a person from Huly. This action cannot be undone. | | list_employees | List employees (persons who are team members). Returns employees sorted by modification date (newest first). | | list_contact_channel_providers | List supported contact channel provider labels for person and organization channel tools. | | list_person_channels | List contact channels for a person. Person accepts person ID, exact email address, or exact Huly display name; ambiguous names fail and should be retried with email or person ID. | | add_person_channel | Idempotently add a contact channel to a person. Person accepts person ID, exact email address, or exact Huly display name. Provider labels match list_contact_channel_providers. Returns added=false and the existing channel when the exact provider+value already exists. | | update_person_channel | Update one contact channel on a person. Person accepts person ID, exact email, or exact display name. Identify the channel with exactly one locator: channelId, or provider plus value. Provide newProvider, newValue, or both. Updating to an existing provider+value on the same person fails with a conflict. | | remove_person_channel | Remove one contact channel from a person. Person accepts person ID, exact email, or exact display name. Identify the channel with exactly one locator: channelId, or provider plus value. Returns removed=false when the locator is absent for that person. | | list_organizations | List all organizations in the Huly workspace. Returns organizations sorted by modification date (newest first). | | create_organization | Create a new organization in Huly. Optionally add members by person ID or email. Fails if any requested member cannot be resolved. Returns the created organization ID. | | get_organization | Retrieve full details for an organization by ID or exact name when that name is unique - including city, description, member count, and modification timestamp. If multiple organizations share the same name, use the organization ID. | | update_organization | Update fields on an existing organization identified by ID or exact name when that name is unique. Only provided fields are modified. Description supports markdown for CRM notes / revenue summaries / context. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Pass null to clear city or description. If multiple organizations share the same name, use the organization ID. | | delete_organization | Permanently delete an organization identified by ID or exact name when that name is unique. Use with care - this cannot be undone. Useful for cleaning up duplicate organizations after merging their data elsewhere. If multiple organizations share the same name, use the organization ID. | | make_organization_customer | Apply the Customer mixin to an organization so it appears in the Huly Leads > Customers view. Idempotent - safe to call on organizations that are already customers. Takes the organization ID or exact name when that name is unique. | | add_organization_channel | Idempotently add a contact channel to an organization identified by ID or exact unique name. Provider labels: email, phone, linkedin, twitter, github, facebook, telegram, homepage, whatsapp, skype, profile, viber. Returns added=false and the existing channel when the exact provider+value already exists. | | list_organization_channels | List contact channels for an organization identified by ID or exact unique organization name. Returns channelId, provider label, value, and optional activity metadata. | | update_organization_channel | Update one contact channel on an organization identified by ID or exact unique name. Identify the channel with exactly one locator: channelId, or provider plus value. Provide newProvider, newValue, or both. Updating to an existing provider+value on the same organization fails with a conflict. | | remove_organization_channel | Remove one contact channel from an organization identified by ID or exact unique name. Identify the channel with exactly one locator: channelId, or provider plus value. Returns removed=false when the locator is absent for that organization. | | add_organization_member | Link a person as a member of an organization. The person appears under the org's Members tab in Huly. Use person ID or email to identify the person. Idempotent: returns added=false if that person is already a member. | | list_organization_members | List all persons who are members of an organization. Returns each member's person ID, name, and primary email (if any). When using a name instead of an ID, that name must identify exactly one organization. | | list_person_organizations | List all organizations that a person is a member of. Provide personId or email. Returns each organization's ID and name. | | remove_organization_member | Unlink a person from an organization's members. Reverses add_organization_member. Returns removed: false if the person was not a member. When using an organization name instead of an ID, that name must identify exactly one organization. |

Channels

| Tool | Description | |------|-------------| | list_chat_message_attachments | List files attached directly to a Huly chat message target. target.kind supports channel_message, dm_message, and thread_reply; the tool resolves channel names and one-to-one DM participant display names for you. | | get_chat_message_attachment | Get one file attached directly to a Huly channel message, direct-message message, or thread reply. The attachmentId must belong to the resolved target. | | add_chat_message_attachment | Attach a file directly to a Huly channel message, direct-message message, or thread reply. Provide filename, contentType, and exactly one source: filePath is resolved on the MCP server host, data is client-local base64 content, and fileUrl is fetched by the MCP server. | | update_chat_message_attachment | Update description and/or pinned state for a file attached directly to a Huly channel message, direct-message message, or thread reply. The attachmentId must belong to the resolved target. | | delete_chat_message_attachment | Delete one file attached directly to a Huly channel message, direct-message message, or thread reply. The attachmentId must belong to the resolved target. | | list_channel_members | List members of a Huly channel by channel name or ID. Returns each member account UUID and the workspace display name when available. | | add_channel_members | Idempotently add members to a non-archived Huly channel. Members accept account UUID, exact email, or exact person display name and resolve to Huly account UUIDs before replacing the full sorted member array. | | remove_channel_members | Idempotently remove members from a non-archived Huly channel. Members accept account UUID, exact email, or exact person display name. Refuses removals that would leave the channel with zero members or, when owners exist, no owner among remaining members. | | join_channel | Join a non-archived Huly channel as the authenticated account. Idempotent when the account is already a member. | | leave_channel | Leave a non-archived Huly channel as the authenticated account. Idempotent when already absent. Refuses to leave if that would leave the channel empty or without any remaining owner. | | archive_channel | Archive a Huly channel by channel name or ID. This is reversible with unarchive_channel and is idempotent when the channel is already archived. | | unarchive_channel | Unarchive a Huly channel by channel name or ID. Idempotent when the channel is already active. | | create_group_direct_message | Open a group direct-message conversation with at least two other workspace members. The people array accepts exact emails or exact display names; the authenticated account is included automatically. Idempotent by exact sorted member set: returns an existing group DM with created: false when one already exists. For one other person, use create_direct_message. | | set_conversation_starred | Set the authenticated user's starred state for exactly one conversation. Provide either channel (channel name or ID) or dm (DM ID, or one-to-one participant display name), plus starred. Creates the missing notification context when needed. | | set_conversation_closed | Set the authenticated user's closed/visible state for exactly one conversation. Provide either channel or dm, plus closed. Closing only hides the current user's notification context; it does not leave channels or remove members. | | list_pinned_chat_messages | List pinned top-level messages and pinned thread replies in exactly one Huly channel or direct-message conversation. Provide channel (name or ID) or dm (DM ID or one-to-one participant name), not both. Results are newest-first across both message kinds. | | set_chat_message_pinned | Idempotently pin or unpin a top-level message or thread reply located inside exactly one Huly channel or direct-message conversation. Provide channel or dm, plus the messageId; the message must belong to the resolved conversation. | | request_channel_access | Attempt the Huly private-channel request-access workflow by channel name or ID. The current Chunter SDK/model has no stable request-access record or server action, so this build returns supported=false with a stable reasonCode and performs no mutation. | | translate_chat_message | Attempt to translate a located Huly channel/DM message to targetLanguage. Current Huly translation is browser-only, uses an optional AI endpoint, and stores results only in UI state; this build returns supported=false with a stable reasonCode and does not fabricate translated text. | | list_channels | List all Huly channels. Returns channels sorted by name. Supports filtering by archived status. Supports searching by name substring (nameSearch) and topic substring (topicSearch). | | get_channel | Retrieve full details for a Huly channel including topic and member list. | | create_channel | Create a new channel in Huly. Returns the created channel ID and name. | | update_channel | Update fields on an existing Huly channel. Only provided fields are modified. | | delete_channel | Permanently delete a Huly channel. This action cannot be undone. For reversible channel lifecycle changes, use archive_channel and unarchive_channel instead. | | list_channel_messages | List messages in a Huly channel. Returns messages sorted by date (newest first). | | list_external_channel_messages | List read-only messages for an external Gmail or Telegram channel by channel name or ID. The limit defaults to 50 and is capped at 200. When this build does not include a compatible Huly external-message SDK/model for the requested provider, returns supported=false, an unsupportedReason, and an empty messages array; it never sends, replies, deletes, mutates, or returns fake messages. | | send_channel_message | Send a message to a Huly channel. Message body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | update_channel_message | Update a channel message. Only the body can be modified; body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | delete_channel_message | Permanently delete a channel message. This action cannot be undone. | | list_direct_messages | List direct message conversations in Huly. Returns conversations sorted by date (newest first). | | create_direct_message | Open a one-to-one direct-message conversation with a workspace member. The person argument accepts an email or exact display name (e.g. Smith,Bill). Idempotent: if a DM with that participant already exists, returns it (created: false); otherwise creates a new DM (created: true). The returned id can be passed as dm to send_dm_message, list_dm_messages, etc. | | list_dm_messages | List messages in a direct-message conversation, newest first. The dm argument accepts either the DM _id or a participant display name (e.g. Kerr,Shannon); a name resolves only to a one-to-one DM with the authenticated account. | | send_dm_message | Send a message to a direct-message conversation. The dm argument accepts either the DM _id or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. Message body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | update_dm_message | Update a direct-message message. The dm argument accepts either the DM _id or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. Only the body can be modified; body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | delete_dm_message | Permanently delete a direct-message message. The dm argument accepts either the DM _id or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. This action cannot be undone. | | list_thread_replies | List replies in a message thread. Returns replies sorted by date (oldest first). | | add_thread_reply | Add a reply to a message thread. Reply body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | update_thread_reply | Update a thread reply. Only the body can be modified; body supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | delete_thread_reply | Permanently delete a thread reply. This action cannot be undone. |

Calendar

| Tool | Description | |------|-------------| | list_events | List calendar events. Returns events sorted by date. Supports filtering by date range. | | list_calendars | List writable, non-hidden calendars that can be used as create_event or create_recurring_event targets. Use this before creating events when you need to choose a target calendarId explicitly. | | get_event | Retrieve full details for a calendar event including description. Use this to view event content and metadata. | | create_event | Create a new calendar event. Description supports markdown formatting. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Optional calendarId targets a specific calendar; when omitted, the event uses the authenticated user's primary personal calendar. Returns the created event ID. | | update_event | Update fields on an existing calendar event. Only provided fields are modified. Description updates support markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | delete_event | Permanently delete a calendar event. This action cannot be undone. | | list_schedules | List calendar scheduling links/availability schedules. Optional owner accepts an employee/person ID, exact name, or email. | | get_schedule | Retrieve one calendar schedule including owner, availability, calendar target, time zone, and room information when it is a meeting schedule. | | create_schedule | Create a calendar schedule. Owner accepts an employee/person ID, exact name, or email; calendar can be targeted by calendarId or calendarName. | | update_schedule | Update a calendar schedule. Supports owner, title, description, duration, interval, availability, timeZone, and calendar move by calendarId or calendarName. | | delete_schedule | Delete a calendar schedule by scheduleId. | | list_recurring_events | List recurring event definitions. Returns recurring events sorted by modification date (newest first). | | create_recurring_event | Create a new recurring calendar event with RFC5545 RRULE rules. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Optional calendarId targets a specific calendar; when omitted, the event uses the authenticated user's primary personal calendar. Returns the created event ID. | | list_event_instances | List instances of a recurring event. Returns instances sorted by date. Supports filtering by date range. Use includeParticipants=true to fetch full participant info (extra lookups). |

Time Tracking

| Tool | Description | |------|-------------| | log_time | Log time spent on a Huly issue. Records a time entry with optional description. Values are hours (Huly native unit): 0.25 = 15 minutes; 8 = one work day. | | get_time_report | Get time tracking report for a specific Huly issue. Shows total time, estimation, remaining time, and all time entries. Values are hours (Huly native unit): 0.25 = 15 minutes; 8 = one work day. | | list_time_spend_reports | List all time entries across issues. Supports filtering by project and date range. Returns entries sorted by date (newest first). Values are hours (Huly native unit): 0.25 = 15 minutes; 8 = one work day. | | get_detailed_time_report | Get detailed time breakdown for a project. Shows total time grouped by issue and by employee. Supports date range filtering. Values are hours (Huly native unit): 0.25 = 15 minutes; 8 = one work day. | | list_work_slots | List scheduled work slots created by schedule_todo, Huly UI, or other clients. Shows planned time blocks attached to ToDos. Supports filtering by employee and date range. | | start_timer | Start a client-side timer on a Huly issue. Validates the issue exists and returns a start timestamp. Use log_time to record the elapsed time when done. | | stop_timer | Stop a client-side timer on a Huly issue. Returns the stop timestamp. Calculate elapsed time from start/stop timestamps and use log_time to record it. |

Search

| Tool | Description | |------|-------------| | fulltext_search | Perform a global fulltext search across all Huly content. Searches issues, documents, messages, and other indexed content. Returns matching items sorted by relevance (newest first). |

Associations

| Tool | Description | |------|-------------| | list_associations | List Huly association definitions: class-level typed links that define which document classes may be related. Use this before create_relation to discover association IDs, source/target classes, and whether relation writes are supported. | | create_association | Idempotently create one Huly association definition between two non-system classes. Use sourceClass/targetClass with sourceRole/targetRole and cardinality; returns an existing identical association by default. | | delete_association | Idempotently delete one Huly association definition only when no concrete relations reference it. If relations exist, delete_relation must clean them up first; deleting an already-missing association is a successful no-op. | | list_relations | List concrete Huly relation instances under an association, optionally filtered by source and target documents. Endpoint locators support raw, issue, document, and card. Requires at least one filter to avoid broad workspace scans. | | create_relation | Idempotently create one concrete relation between two resolved documents for a writable association. Endpoint locators support raw, issue, document, and card. Enforces association endpoint classes, direction, duplicate handling, automation-only restrictions, and cardinality. | | delete_relation | Idempotently delete one concrete relation by relation ID or by exact association/source/target triple. Triple endpoint locators support raw, issue, document, and card. Triple deletes use the same direction semantics as create_relation and fail if the selector is ambiguous. |

Activity

| Tool | Description | |------|-------------| | list_activity | List activity messages for a Huly issue, document, channel, or raw Huly object. Prefer friendly targets: project+issueIdentifier for issues, teamspace+document for documents, or channel for channels. Advanced callers may pass objectId+objectClass directly. Returns activity sorted by date (newest first). Legitimately absent or null optional actor, message, class, and metadata fields are omitted from each item. | | get_activity_message | Get a single activity message by ID, including subclass metadata when available. | | pin_activity_message | Pin or unpin an activity message. Idempotent when the pin state already matches. | | list_activity_filters | List configured activity filters in display order. | | list_activity_references | List activity references connected to a raw Huly object. Use direction to list references from the object, to the object, or both. | | list_activity_replies | List thread replies on any activity message, not only channel messages. | | add_activity_reply | Add a Markdown reply to any activity message. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | update_activity_reply | Update a generic activity reply body. Body supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | delete_activity_reply | Delete a generic activity reply. | | add_reaction | Add an emoji reaction to an activity message. | | remove_reaction | Remove an emoji reaction from an activity message. | | list_reactions | List reactions on an activity message. | | save_message | Save/bookmark an activity message for later reference. | | unsave_message | Remove an activity message from saved/bookmarks. | | list_saved_messages | List saved/bookmarked activity messages. | | list_mentions | List @mentions of the current user in activity messages. |

Notifications

| Tool | Description | |------|-------------| | list_notification_providers | List model-declared notification providers such as inbox, push, and sound. Use returned provider IDs for setting updates. Older REST servers may return compatibility metadata with an explicit tool warning. | | list_notification_types | List model-declared notification types. Use returned type IDs for provider-specific setting updates. Older REST servers may return compatibility metadata with an explicit tool warning. | | list_notifications | List inbox notifications. Returns notifications sorted by modification date (newest first). Supports filtering by read/archived status. | | get_notification | Retrieve full details for a notification. Use this to view notification content and metadata. | | mark_notification_read | Mark a notification as read. Idempotent: returns success when the notification is already read. | | mark_notification_unread | Mark a notification as unread. Idempotent: returns success when the notification is already unread. | | mark_all_notifications_read | Mark all unread notifications as read. Returns the count of notifications marked. | | archive_notification | Archive a notification. Archived notifications are hidden from the main inbox view. Idempotent when already archived. | | unarchive_notification | Unarchive a notification so it can appear in active notification lists again. Idempotent when already active. | | archive_all_notifications | Archive all notifications. Returns the count of notifications archived. | | delete_notification | Permanently delete a notification. This action cannot be undone. | | get_notification_context | Get notification context for an entity. Returns tracking information for a specific object. | | list_notification_contexts | List notification contexts. Returns contexts sorted by last update timestamp (newest first). Supports filtering by pinned status and can include hidden contexts. | | pin_notification_context | Pin or unpin a notification context. Pinned contexts are highlighted