Huly MCP MCP Server

Huly MCP

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

It connects to Huly Platform deployments and should also work with the Platform Collective and TraceX forks. Intabia 0.8.33 / model 0.8.4 has been compatibility-tested; known gaps are tracked in issue #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 is a feature-complete command-line interface for Huly, published as @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 for the complete generated command reference, or browse CLI examples, Huly automation patterns, and the Huly MCP vs CLI comparison.

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:

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 uses a Huly API token and 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_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Prefer a managed API token created in Huly account settings when the target deployment supports it. Managed tokens are bound to one workspace, assigned an expiry, and can be revoked without changing the account password. They still inherit the account's full rights in that workspace, so use a dedicated integration account with only the workspace role, space memberships, and data access the automation needs. Older Huly deployments may not expose managed token settings; email/password authentication remains available as a compatibility fallback.

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_TOKEN=your-huly-api-token \
  --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_TOKEN = "your-huly-api-token"
HULY_WORKSPACE = "yourworkspace"

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

claude mcp add huly \
  -e HULY_URL=https://your-huly-instance.example.com \
  -e HULY_TOKEN=your-huly-api-token \
  -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_TOKEN": "your-huly-api-token",
        "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_TOKEN": "your-huly-api-token",
        "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:

pi install npm:pi-mcp-adapter

See the Pi setup guide 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:

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 for preflight checks, rerun behavior, and verification.

HTTP Transport

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

HULY_URL=https://your-huly-instance.example.com \
HULY_TOKEN=your-huly-api-token \
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 transports are implemented with Effect AI's MCP server and protocol adapters. The server configures the released MCP 2026-07-28 stateless protocol and the MCP 2025-06-18 compatibility protocol. 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. Legacy HTTP supports initialized sessions using the returned Mcp-Session-Id and bare stateless calls with request-local bindings. Huly credentials are configured separately through env vars or supported x-huly-* headers.

See MCP transport architecture and certification for the implementation boundary and the current verification record.

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 supported x-huly-* header is present, all required headers must be present and unsupported x-huly-* headers are rejected. Requests with only unsupported x-huly-* headers (for example a proxy trace id) use the process environment configuration. 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_TOKEN	Auth*	Preferred: managed Huly API token where supported
HULY_EMAIL	Auth*	Compatibility fallback: account email
HULY_PASSWORD	Auth*	Compatibility fallback: account 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
HULY_MCP_TELEMETRY	No	Aggregate usage analytics (PostHog), on by default. Set 0 to disable. DO_NOT_TRACK=1 also disables it.

*Auth: Prefer HULY_TOKEN. Use HULY_EMAIL + HULY_PASSWORD only when the Huly deployment does not support a managed API token or another compatibility constraint requires password authentication.

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, hr, inventory, labels, leads, mail, templates, model-administration, planner, preferences, processes, recruiting, sdk-discovery, security-administration, sequence-administration, spaces, support, tag-categories, tags, task-management, test-management, user-statuses, views, virtual-office, workbench, 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_external_tracker_targets	List external issue-tracker targets mapped to a Huly project. Omit provider to list every provider supported by this server, or pass provider:'github' to list mapped GitHub repositories. Returns each target's provider, kind, stable Huly ID, exact name, enabled state, and an actionable unavailable reason when known. This discovers Huly configuration only; it does not call the external provider or prove that the synchronization worker is running.
publish_issue_to_external_tracker	Request publication of an existing Huly issue as a new issue in Huly's configured external tracker. Identify the issue with project and its human identifier (for example, HULY-123); provider currently accepts only 'github'. Select target by stable Huly target ID or exact name, or omit target only when exactly one enabled target is mapped to the project. Publication is asynchronous: pending means Huly accepted the request, not that an external issue exists. Repeating the same target is safe while pending or published; a failed same-target request retries, while a different target is rejected. Use get_issue_publication_status to observe completion.
get_issue_publication_status	Read the Huly-persisted external publication state for an issue identified by project and human issue identifier. Returns not_requested, pending, published, or failed; pending includes the ISO state-change timestamp and elapsed time, while published includes an external URL and positive issue number. A timeout is projected as failed only after the bounded wait, and later persisted publication takes precedence. This reads Huly state and never calls the external provider directly.
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 (email, Person display name, or exact agent UserProfile title), 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. Assignee accepts an email, Person display name, or exact agent UserProfile title and always stores the linked Person. 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. Assignee accepts an email, Person display name, or exact agent UserProfile title and always stores the linked Person; use null to unassign. 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.
list_document_label_definitions	List label definitions available for ordinary Huly documents by optional title substring. Does not expose raw target-class or category mechanics.
list_document_labels	List labels attached to one ordinary Huly document. Resolves the teamspace by name or ID and the document by title or ID; no raw class, space, or collection values are needed.
add_document_label	Idempotently attach a label to an ordinary Huly document resolved by teamspace and title or ID. label accepts a definition ID or exact title; a missing title creates the document label definition first, while duplicate exact titles return candidate IDs.
remove_document_label	Detach a label from one ordinary Huly document without deleting the reusable label definition. Returns detached=false when the label exists but is not attached; duplicate exact titles return candidate IDs.

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_employees	List employees (persons who are team members), sorted by modification date (newest first). Each summary exposes stable Contact Employee fields city, email, role, statuses count, personUuid, position, active, and modifiedOn. SDK avatarType/avatar/avatarProps are provider/blob metadata; attachment/comment/channel counters and social identity collections are derived; birthday/profile need separate contracts; createdOn/createdBy/modifiedBy and class/space refs are internal metadata and intentionally unsupported in this projection.
set_employee_position	Idempotently set an employee's official position on contact.mixin.Employee. employee must be an object with exactly one locator field: {id}, {email}, or {name}; combined locator modalities are rejected. The selected ID, email, or display name is exact, and duplicate email/name matches are rejected. The position field is required: pass a string to set it, or null/an empty string to clear it. Omitting position fails schema parsing and performs no mutation. This updates the Contact Employee mixin, not an HR Staff record.
invite_employee	Create or promote and invite an employee, or resend an inactive employee invitation. mode=create-or-promote requires the exact Huly display name and email; one checked atomic transaction creates or updates the Person, email SocialIdentity, and active Employee before sending. A changed authoritative precondition sends no invite and directs the caller to retry in a fresh session. mode=invite-existing requires an exact email/name locator and rejects active or non-Employee targets. Omitted role preserves the Employee role; an explicit different role is persisted atomically before resend. Returns no invitation link, credential, or token; an invitation-provider failure reports completed preparation.
list_inactive_employees	List every inactive Employee before applying output pagination. Each result distinguishes the account link, workspace membership and role, Person identity, and Employee active state so an agent can choose reinvite, deactivate, or kick safely.
deactivate_employee	Preview or execute an employee lifecycle change resolved by exact email or exact display name. action=deactivate only sets Employee.active=false and retains workspace membership; action=kick then removes the linked account from the workspace. If workspace removal fails after deactivation, the typed partial failure lists completed changes and directs a safe preview-and-retry. Preview is the default. Execution requires execute=true plus one exact expected relationship object copied from the preview: unlinked, linked-without-membership, or workspace-member. Any changed Person ID, account UUID, Employee active flag, membership, or workspace role is rejected. The authenticated employee cannot target itself.
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_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.
make_person_customer	Apply the native Customer mixin to one existing person so it appears in Huly Leads > Customers. Resolve by person ID, exact email address, or exact display name; ambiguous identifiers fail, no person is created, and repeated calls are idempotent.
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.
merge_people	Preview or execute a native-reference-preserving person merge with an explicitly selected source and survivor; source and survivor must each contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous. Preview is the default and reports identities, channels, memberships, comments, attachments, every other model-declared Person/Contact/Employee reference, account eligibility, retained scalar fields, and an exact preflight token bound to canonical affected document IDs, write-routing fields, and scalar/array values. Execution requires execute=true plus that current token, rejects any snapshot drift before writing, rewires scalar and array references without dropping other array members, and invokes Huly's global Person merge when applicable. The source workspace Person record is retained because Huly's native merge does not cascade-delete it.
get_person_administration	Inspect one person's identity and profile administration surface; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous. Returns contact statuses, workspace membership, avatar metadata, birthday, social identities, account profile, channel activity, and an explicit stable-field support ledger.
list_social_identity_providers	List SocialIdentity providers installed in this Huly workspace, returning native provider IDs and types.
repair_person_social_identities	Apply only Huly's native safe, idempotent SocialIdentity repairs from the authenticated person's authoritative account record: recreate missing active projections, promote verification, reassign an unverified identity after an account merge, and propagate authoritative deletion; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous. Another account-linked person, verified cross-person reassignment, arbitrary active type/value/key changes, removal of workspace-only identities, and key collisions return a Huly-specific unsupported reason instead of being overwritten.
list_person_comments	List notes/comments genuinely attached to one person, oldest first; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous.
add_person_comment	Add a markdown note/comment to one person; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous. 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_person_comment	Idempotently update a note/comment belonging to one resolved person; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous. 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_person_comment	Permanently delete a note/comment only when it belongs to one resolved person; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous.
list_person_attachments	List attachments genuinely attached to one person; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous.
add_person_attachment	Upload and attach a file to one person from exactly one of filePath, fileUrl, or base64 data; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous.
get_person_attachment	Get an attachment only when it belongs to one resolved person; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous.
update_person_attachment	Update description or pinned state only when the attachment belongs to one resolved person; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous.
delete_person_attachment	Permanently delete an attachment only when it belongs to one resolved person; person must contain exactly one exact locator: {id}, {email}, or {name}; duplicate email/name matches fail as ambiguous.

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	Read persisted Telegram contact-channel messages or assess why an external provider cannot be read safely. For provider=telegram, resolve channel by exact stored value or stable contact-channel ID and return newest contentMarkdown, direction, stored Huly sendOn timestamp, and attachment count; returns supported=false when the workspace model or channel is unavailable. Inbound attachment creation is asynchronous, so attachmentCount can temporarily lag the message; attachment bytes are not returned. This proves only Huly-stored records, not provider freshness, an active Telegram connection, or provider delivery/read status. Gmail returns supported=false because Huly does not expose the live deployment-wide v1/v2 writer version needed to distinguish current legacy records from stale data. The limit defaults to 50 and is capped at 200. This tool never sends, replies, deletes, or mutates.
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 a