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.

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"

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.

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

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

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

Add the standard config to your Windsurf MCP configuration file.

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

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.

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.

Manual resident backend

The experimental manual resident backend path lets independent stdio hosts select one explicitly started local backend through a private attachment file. Full qualification remains pending.

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.

Shared CLI and stdio profiles

Save a profile with huly auth login --profile work, then set HULY_PROFILE=work in the stdio MCP server's environment. Both processes must run under the same OS user and configuration directory. Stdio never follows the active CLI profile implicitly. Saved tokens are bound to their instance URL and workspace; changes require login again or complete environment credential injection. See the CLI profile instructions. HTTP configuration remains unchanged.

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_PRELOAD_TOOLS	No	Load every tool handler before serving requests. Defaults to false; use true for smoke tests that check all handler imports.
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.

Startup and initialization

Tool discovery reads a generated catalog without loading operation handlers or waiting for Huly. Handlers load by tool group on demand; concurrent calls share the group's load. Run pnpm update-tool-catalog after changing tool definitions. Builds reject a stale catalog.

For stdio, the first tool-list request starts the process-owned Huly connection in the background. Calls that need the full Huly model wait for the same initialization. Cancelling a waiting call does not cancel initialization for other calls. A failed model initialization can be retried by a later call. Project listing uses a separate REST read and does not wait for the full model. Other operations retain the full model and their existing behavior.

The default transport remains stdio: each process launched by an MCP host owns its connection and model. HTTP lets clients share one running server. Connections created from request credential headers initialize the model only when needed; the CLI also uses this on-demand policy.

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.

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

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