Huly MCP is a fully featured MCP server for the Huly platform, and it also maintains the corresponding Huly CLI in the same repository. The two share the same operation registry, so the inputs, outputs, warnings, and typed failures of operations remain consistent. Huly MCP is published as the npm package @firfi/huly-mcp, and Huly CLI is published as @firfi/huly-cli.
Purpose Huly MCP is used to connect the Huly platform to MCP-compatible clients, enabling clients to query issues, create and update tasks, manage labels and priorities, and perform other operations on the Huly platform. It connects to Huly Platform deployments, and is officially said to also be applicable to the Platform Collective and TraceX branches; compatibility testing has been done for Intabia 0.8.33 / model 0.8.4, known gaps are recorded in issue #279, and branch support remains unofficial.
Main capabilities Huly MCP provides a fully featured set of Huly operations, covering categories such as projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendars, time tracking, search, relations, activity, notifications, workspaces, approvals, kanban, cards, collaborators, custom fields, Drive, HR, inventory, labels, leads, mail, templates, model management, planner, preferences, processes, recruitment, SDK discovery, security management, sequence management, spaces, support, tag categories, tags, task management, test management, user status, views, virtual office, workbench, workflow status, and more.
Tool exposure modes By default, with HULY_TOOL_MODE=auto, to avoid listing about 470 tools at once, Huly MCP is optimized for the current MCP client: 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 interface, including list_tool_categories, search_tools, get_tool_schema, and invoke_tool. Native tool names can still be dispatched when called directly by the client, but many clients only call the tools returned by tools/list. HULY can be set_TOOL_MODE=native makes all Huly tools appear as first-class tools, or use TOOLSETS / TOOLS to pin commonly used native tools while retaining agent discovery capability.
Usage Huly MCP requires Node.js 22.19.0 or higher. MCP clients do not provide a Node.js runtime; node, npx, and package executables resolve Node.js from the environment in which the MCP client runs, so that environment must be checked before installation. If an MCP client starts Huly MCP with an older runtime, the server initializes a diagnostic-only MCP interface instead of loading the incompatible application; its server instructions and the get_huly_startup_diagnostic tool report the detected executable and required version, and the same unsupported-runtime diagnostic is also written to stderr. Upgrade Node.js or configure the MCP server command to use an absolute path to a compatible Node.js executable, then restart the MCP server; until the runtime is upgraded, Huly operations are unavailable.
Standard configuration uses a Huly API token and works with most MCP clients. When the target deployment supports it, prefer a managed API token created in the Huly account settings. Managed tokens are bound to a single workspace, are assigned an expiration time, and can be revoked without changing the account password. They still inherit all of the account's permissions in that workspace, so a dedicated integration account should be used, granting only the workspace roles, space memberships, and data access required for automation. Older Huly deployments may not offer managed token settings; email/password authentication remains available as a compatibility fallback.
Installation and Configuration It can be added through Codex's MCP manager, or written directly to ~/.codex/config.toml; it can also be added to ~/.claude.json using the standard configuration. Claude Desktop can be added to claude_desktop_config.json, at the macOS path ~/Library/Application Support/Claude/claude_desktop_config.json, and the Windows path %APPDATA%\Claude\claude_desktop_config.json. VS Code It can be added through the command palette's "MCP: Add Server", or written to a VS Code MCP configuration such as .vscode/mcp.json; do not commit workspace configuration files containing real credentials. Cursor can be added to ~/.cursor/mcp.json, or through Settings → Tools & Integrations → New MCP Server. Windsurf is added to its MCP configuration file. OpenCode opens the global configuration file ~/.config/opencode/opencode.json and merges the entry. Pi requires an MCP adapter; after installation, use Huly MCP in auto mode and promote the four agent tools to Pi's native tool list.
The @latest tag requests the latest version from the package runner. Some MCP clients keep the server process or resolved installation active, so updates require restarting or re-adding the server.
Transport By default the server uses stdio transport. For HTTP transport, the server listens by default on http://127.0.0.1:3000/mcp，可通过 MCP_HTTP_PORT and MCP_HTTP_HOST configuration. Both transports use Effect AI's MCP server and protocol adapter implementations. The server implements the published MCP 2026-07-28 stateless protocol and the MCP 2025-06-18 compatibility protocol. Modern HTTP requires one JSON-RPC message per POST, with 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, as well as bare stateless calls with request-local bindings. Huly credentials are configured separately via environment variables or the supported x-huly-* headers.
For hosted or tunneled HTTP deployments, a bearer token can be required for the MCP endpoint. MCP_AUTH_TOKEN only protects the MCP HTTP /mcp endpoint, is unrelated to HULY_TOKEN, is not used to authenticate to Huly, and does not replace HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN. Huly credentials must still be provided via process environment variables, or via the supported x-huly-* headers in hosted URL deployments. stdio deployments do not use MCP_AUTH_TOKEN.
Shared CLI and stdio configuration You can use huly auth login --profile work to save the configuration, then set HULY_PROFILE=work in the stdio MCP server environment. Both processes must run under the same operating system user and configuration directory. stdio does not implicitly follow the active CLI configuration. Saved tokens are bound to their instance URL and workspace; changing them requires logging in again or fully injecting environment credentials.
Hosted HTTP header configuration For hosted URL deployments, keep the server process configured with MCP_TRANSPORT=http. The hosting layer can forward per-session Huly credentials as request headers, allowing one hosted serverServe different Huly workspaces without process-level HULY_* environment variables. Among the supported v1 headers, if any supported x-huly-* header is present, all required headers must be present, and unsupported x-huly-* headers are rejected. Requests containing only unsupported x-huly-* headers (for example, proxy tracing IDs) use the process environment configuration. Missing values are not filled in from environment variables. Managed header configuration v1 does not support email/password authentication.
Environment variables Authentication prefers HULY_TOKEN. Use HULY_EMAIL + HULY_PASSWORD only when the Huly deployment does not support managed API tokens or other compatibility constraints require password authentication.
Built-in diagnostic tools get_version returns the current server version and the latest npm version. get_huly_context returns the sanitized runtime/configuration context of the current MCP session without connecting to Huly. It reports the package version, transport, authentication mode, sanitized Huly URL origin/host/protocol, workspace, timeout, configuration source, native tool scope filtering, and the resolved native/proxy tool exposure. Tokens, passwords, email values, credential headers, URL paths, URL query strings, and URL credentials are never returned.
The server exposes read-only MCP Resources as JSON context for clients that support resources/read. resources/list returns concrete active project resources. Issue resources are template-based: use resources/templates/list to discover the supported issue URI templates, then read known issue URIs.
Applicable scenarios Suitable for scenarios that need to connect the Huly platform to MCP clients for project management and task automation, and also suitable for scenarios that need terminal-native Huly integration, scripting, and automation alternatives. The Huly CLI provides exactly the same Huly operations as Huly MCP, exposed as native, schema-aware commands, supporting human-readable or JSON output, file input, upload, and download.
Limitations Huly MCP requires Node.js 22.19.0 or higher; when the runtime version does not meet this, Huly operations are unavailable. Branch support is unofficial. Managed header configuration v1 does not support email/password authentication. If the Huly password contains *, %, !, or # or other characters, passing it through CLI environment flags may fail because the shell interprets the characters before they reach the process; the solution is to edit the MCP configuration file directly. After changing the MCP configuration, some clients (including Claude Code) require a full restart rather than just reconnecting. Self-hosted Huly locks password login after 5 failed API authentication attempts; this lock persists across service restarts in the database and requires resetting the lock counter in CockroachDB. On Windows, Bash wrapper scripts (sourcing .env files) launched by the MCP client may not work reliably; it is recommended to set environment variables directly in the MCP configuration JSON; on Windows, pulling Docker images over SSH may fail due to credential manager issues.