# Huly Mcp

> Huly MCP: Feature-complete MCP server for Huly platform

- **Type:** MCP server
- **Install:** `agentstack add mcp-dearlordylord-huly-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dearlordylord](https://agentstack.voostack.com/s/dearlordylord)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dearlordylord](https://github.com/dearlordylord)
- **Source:** https://github.com/dearlordylord/huly-mcp
- **Website:** https://huly-mcp.dearlordylord.com

## Install

```sh
agentstack add mcp-dearlordylord-huly-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Huly MCP

[](https://www.npmjs.com/package/@firfi/huly-mcp)
[](https://www.npmjs.com/package/@firfi/huly-mcp)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://www.typescriptlang.org/)
[](https://glama.ai/mcp/servers/@dearlordylord/huly-mcp)
[](https://github.com/dearlordylord/huly-mcp)[](https://monadical.com)

**Huly MCP** is a feature-complete MCP server for [Huly](https://huly.io/) integration. Published on npm as [`@firfi/huly-mcp`](https://www.npmjs.com/package/@firfi/huly-mcp).

## Installation

The standard configuration works with most MCP clients:

```json
{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}
```

## Tool Exposure Defaults

By default (`HULY_TOOL_MODE=auto`), Huly MCP optimizes for current MCP clients by avoiding a 470-tool eager list. Exact `claude-code` sessions receive native Huly tools. Codex, Cursor, Windsurf, Copilot, OpenCode, Claude AI/Desktop-style clients, and unknown clients receive a small proxy surface: `list_tool_categories`, `search_tools`, `get_tool_schema`, and `invoke_tool`.

Exact native tool names still dispatch when a client calls them directly, but many clients only call tools returned by `tools/list`. Set `HULY_TOOL_MODE=native` to make every Huly tool appear first-class, or use `TOOLSETS` / `TOOLS` to pin frequently used native tools while keeping proxy discovery available.

Codex

Use Codex's MCP manager:

```bash
codex mcp add huly \
  --env HULY_URL=https://huly.app \
  --env HULY_EMAIL=your@email.com \
  --env HULY_PASSWORD=yourpassword \
  --env HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest
```

Or add it directly to `~/.codex/config.toml`:

```toml
[mcp_servers.huly]
command = "npx"
args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env]
HULY_URL = "https://huly.app"
HULY_EMAIL = "your@email.com"
HULY_PASSWORD = "yourpassword"
HULY_WORKSPACE = "yourworkspace"
```

Claude Code

```bash
claude mcp add huly \
  -e HULY_URL=https://huly.app \
  -e HULY_EMAIL=your@email.com \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest
```

Or add to `~/.claude.json` using the standard config above.

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.

```json
{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "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:

```json
{
  "mcp": {
    "huly": {
      "type": "local",
      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}
```

## Updating

The `@latest` tag asks the package runner for the newest version. Some MCP clients keep server processes or resolved installs alive, so restart or re-add the server when updating:

| Client | How to update |
|--------|--------------|
| **Codex** | `codex mcp remove huly` then re-add with the install command above. If your password has shell-sensitive characters, edit `~/.codex/config.toml` directly instead |
| **Claude Code** | `claude mcp remove huly` then re-add with the install command above |
| **Claude Desktop** | Restart the app (it runs `npx` on startup) |
| **VS Code / Cursor** | Restart the MCP server from the command palette/configured client or reload the window |
| **OpenCode** | Restart OpenCode or start a new session after config changes |
| **npx (manual)** | `npx -y @firfi/huly-mcp@latest` — the `-y` flag auto-confirms install prompts |

## HTTP Transport

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

```bash
HULY_URL=https://huly.app \
HULY_EMAIL=your@email.com \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/huly-mcp@latest
```

Server listens on `http://127.0.0.1:3000/mcp` by default.

Configure with `MCP_HTTP_PORT` and `MCP_HTTP_HOST`:

```bash
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-mcp@latest
```

### HTTP MCP Protocol Support

The HTTP server supports both the existing SDK initialize-compatible Streamable HTTP flow and the 2026 stateless HTTP flow at the same `/mcp` endpoint. Dispatch is per request:

- Requests with `MCP-Protocol-Version: 2026-07-28`, matching `_meta.io.modelcontextprotocol/protocolVersion`, or `server/discover` use the 2026 stateless dispatcher.
- Requests without 2026 protocol signals continue through the SDK transport for compatibility with existing clients.

The 2026 path requires one JSON-RPC message per POST, `Accept: application/json, text/event-stream`, `Mcp-Method`, method-specific `Mcp-Name`, and per-request `_meta.io.modelcontextprotocol/*` client metadata. Huly credentials are still configured separately through env vars or supported `x-huly-*` headers.

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

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

HTTP clients must then send:

```http
Authorization: Bearer 
```

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

### Hosted HTTP Header Configuration

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

Supported v1 headers:

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

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

For a Smithery publish schema example, see [docs/SMITHERY_URL_PUBLISH.md](docs/SMITHERY_URL_PUBLISH.md).

## Environment Variables

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

*Auth: Provide either `HULY_EMAIL` + `HULY_PASSWORD` or `HULY_TOKEN`.

## Built-in Diagnostic Tools

`get_version` returns the current server version and latest npm version.

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

## MCP Resources

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

| 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](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`, `inventory`, `labels`, `leads`, `templates`, `planner`, `preferences`, `processes`, `recruiting`, `sdk-discovery`, `spaces`, `tag-categories`, `tags`, `task-management`, `test-management`, `user-statuses`, `views`, `virtual-office`

### Projects

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

### Issues

| Tool | Description |
|------|-------------|
| `preview_deletion` | Preview the impact of deleting a Huly entity before actually deleting it. Shows affected sub-entities, relations, and warnings. Supports issues, projects, components, and milestones. Use this to understand cascade effects before calling a delete operation. |
| `list_components` | List components in a Huly project. Components organize issues by area/feature. Returns components sorted by modification date (newest first). |
| `get_component` | Retrieve full details for a Huly component. Use this to view component content and metadata. |
| `create_component` | Create a new component in a Huly project. Components help organize issues by area/feature. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Returns the created component ID and label. |
| `update_component` | Update fields on an existing Huly component. Only provided fields are modified. Description supports markdown. Markdown links to current-workspace Huly browse URLs with _class, _id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. |
| `set_issue_component` | Set or clear the component on a Huly issue. Pass null for component to clear it. |
| `delete_component` | Permanently delete a Huly component. This action cannot be undone. |
| `list_issu

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dearlordylord](https://github.com/dearlordylord)
- **Source:** [dearlordylord/huly-mcp](https://github.com/dearlordylord/huly-mcp)
- **License:** MIT
- **Homepage:** https://huly-mcp.dearlordylord.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-dearlordylord-huly-mcp
- Seller: https://agentstack.voostack.com/s/dearlordylord
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.