Huly MCP

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": { "MCP_TRANSPORT": "stdio-resident", "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.

Codex

npx automatically downloads and caches Huly MCP; pnpm dlx @firfi/huly-mcp@latest is an alternative. Huly is optional, so Codex can start without it and a cold download may leave the first turn without Huly tools. Run /mcp to check the connection.

Add to ~/.codex/config.toml (the 120-second startup allowance includes installation):

[mcp_servers.huly]

startup_timeout_sec = 120 command = "npx" args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env] MCP_TRANSPORT = "stdio-resident" HULY_URL = "https://your-huly-instance.example.com" HULY_TOKEN = "your-huly-api-token" HULY_WORKSPACE = "yourworkspace"

Claude Code

claude mcp add huly \

-e MCP_TRANSPORT=stdio-resident \ -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.

Claude Desktop

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

VS Code

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": { "MCP_TRANSPORT": "stdio-resident", "HULY_URL": "https://your-huly-instance.example.com", "HULY_TOKEN": "your-huly-api-token", "HULY_WORKSPACE": "yourworkspace" } } } }

Cursor

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

Windsurf

Add the standard config to your Windsurf MCP configuration file.

OpenCode

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": { "MCP_TRANSPORT": "stdio-resident", "HULY_URL": "https://your-huly-instance.example.com", "HULY_TOKEN": "your-huly-api-token", "HULY_WORKSPACE": "yourworkspace" } } } }

Pi

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:

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.

Shared resident stdio

The setup examples explicitly select MCP_TRANSPORT=stdio-resident. MCP clients still use stdio, while compatible clients under the same OS user share a Node backend through small native bridges. Linux and macOS arm64/x64 binaries are included; no Rust installation is needed. Application requests remain buffered during the 30-second resident startup budget. Startup failure launches ordinary stdio and dispatches the buffered application input once. A failed active resident never reconnects or replays application requests.

Omitting MCP_TRANSPORT still selects ordinary stdio, preserving existing installations. Set MCP_TRANSPORT=stdio explicitly to keep a separate backend per client. Restart the MCP client after changing the setting.

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]