Huly MCP Server

Huly MCP

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

Installation

The standard configuration works with most MCP clients:

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

Use Codex's MCP manager:

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:

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

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://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "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://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:

HTTP Transport

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

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:

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:

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:

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.

Environment Variables

*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, and toolset filtering. 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/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.

Roadmap

The roadmap is driven by SDK parity and the project principle that this server should expose LLM-first tools: clear names, self-contained parameters, automatic identifier resolution, and single-call correctness. The audited source of truth lives in plans/huly-sdk-gap-matrix.md, with machine-checkable classifications in plans/sdk-parity-ledger.json.

Highest-value additions for coding agents:

• Generic space follow-ups: role/permission definition writes, generic space creation, and module-specific wrappers above the shared space foundation. Generic space metadata, member/owner mutations, and typed-space role member mutations are covered by the shared spaces tools.
• Core schema/admin follow-ups: guarded attribute/enum writes, role/permission definition writes, generic space creation, global space admins, and module-specific wrappers above the shared space foundation.
• Drive follow-ups: drive create/update/delete, item move/rename/delete, adding new versions to existing files, permissions, and comments/activity.
• Team planner/reporting: team agendas, workload/capacity summaries, visibility-aware free/busy views, document action items, and planner automation diagnostics.
• Recruiting: vacancies, candidates, applications, application statuses, recruiter assignment, reviews, opinions, skills, and related comments/attachments/activity.
• Controlled documents and trainings: controlled document spaces/projects, review/approval workflows, templates, categories, snapshots/history, training assignments, attempts, scoring, and results.
• Module-specific tag wrappers for tag-backed concepts such as recruiting skills, board labels, controlled-document labels, and contact tags.

Planned feature surfaces:

• Implemented foundation: generic space discovery and safe existing-space administration are covered by spaces tools for listing/getting spaces, listing/getting space types, reading permissions, updating common metadata, adding/removing members, and replacing owners.
• Controlled Documents / TraceX documents: controlled spaces/projects, controlled document CRUD, quality/technical docs, co-authors/reviewers/approvers, e-signature workflows, release/effective-date metadata, change control, training linkage, controlled-document comments, and snapshots/history.
• Products and product versions: product spaces, members, descriptions, attachments, versions, version state transitions, and change-control links.
• Trainings, questions, and assessments: training revisions, releases, requests, due dates, max attempts, question banks, answer options, correct-answer data, submissions, scoring, and reporting.
• Drive: first slice covers listing/getting drives, path traversal/list/get items, idempotent folder creation, uploads with parent creation, version listing, and restoring existing versions. Remaining gaps are drive create/update/delete, item move/rename/delete, adding new versions to existing files, comments/activity, and permissions/members.
• HR: departments, nested departments, staff mixins, managers, subscribers, team leads, request types, PTO/sick/overtime/remote requests, public holidays, and schedule/table reports.
• Recruiting: vacancies, talents/candidates, applications, matches, reviews, verdicts/opinions, vacancy-company lists, skills, and recruiting-specific custom fields/relations.
• Surveys and polls: survey CRUD, poll creation/attachment, survey question data, completion status, and results.
• Generic approval requests: create/list/approve/reject/cancel approval requests, decision comments, required approval counts, request status, and requested/approved/rejected people.
• Boards: board CRUD, board cards, status workflows, members/assignees, location, cover/archive fields, board labels, and menu/archive views.
• Inventory: category hierarchy CRUD, product CRUD, variant/SKU CRUD, and product-scoped photo, attachment, comment, and activity wrappers are covered by first-class tools; category/variant discussion wrappers remain outside this slice.
• Leads write surface: create/update/delete funnels and leads, status changes, assignment, start dates, customer descriptions, person customer support, and lead comments/attachments/labels/relations.
• Contacts: person channels, social identities, provider discovery, contact statuses, notes/comments, person attachments, person merge, employee invite/create/kick/reinvite, and inactive employee management.
• Calendar: calendar CRUD/config, external calendar sync metadata, primary calendar management, schedule objects, participant mutations, and RSVP/status support when stable.
• Team planner and schedule reporting: team agendas, workload/capacity summaries, and visibility-aware free/busy views across members/projects.
• Virtual office and meetings: offices, floors, rooms, access/language/default recording/transcription settings, meeting schedules, active participants, room info, meeting notes/transcript records (minutes), recordings, and device preferences.
• Chat and communication: request-access flows if Huly exposes a stable model, pinned messages, translation, applets, in-message polls, guest communication settings, and external Gmail/Telegram/Huly Mail surfaces plus provider-specific attachments once compatible packages/APIs are proven.
• Notifications and activity: browser/push subscription internals, provider defaults, UI presenter/viewlet metadata, and activity control/extension metadata.
• Attachments and media: previews/preview metadata and friendly wrappers for additional object types beyond issue/document/inventory product.
• Core schema and workspace administration: attribute/property create/update/delete/hide, enum CRUD/options, sequence management, role/permission definition writes, generic space creation, global space admins, integrations registry, invite settings, role capability settings, and workspace setting metadata.
• Integrations: GitHub repository/project mappings and sync metadata (deferred), Google Calendar connect/configure/sync controls, Bitrix entity/field mappings and sync status, Gmail/email channel messages, Telegram messages, Huly Mail/Mail plugin behavior, AI assistant integration state, and AI bot configuration if server-side APIs expose stable behavior.
• Templates, rating, support, billing, analytics, views, workbench, and preferences: read-only message template/category/field discovery is covered; message template writes/rendering remain deferred until provider semantics are proven. Document/person rating data is blocked by unpublished @hcengineering/rating SDK package (#90); support conversations, billing tier/status discovery, onboarding channels, saved filtered views, user view preferences, tabs/widgets/apps, and module preference discovery/update remain future surfaces.
• Document-specific gaps: snapshot restore, backlinks, notes, structured action items/tables, PDF/export, advanced document relationships, and document printing/export once SDK support is safe.

MCP resource roadmap:

• Return resource links from list/search tool results for direct resources/read follow-up.
• Add document resources when document reads have a stable URI shape and context-friendly payload.
• Consider scoped/paginated issue listing only when filters prevent very large resources/list responses.
• Consider resource subscribe and listChanged support after stateful sessions and a Huly change source are available.

SDK upgrade revisit:

• Revisit @hcengineering/* upgrades when a newer release is available after 0.7.423.
• Verify published tarballs, not only npm metadata, before accepting SDK upgrades.
• Require valid published declaration files for direct Huly dependencies.
• Upgrade direct Huly package declarations coherently in package.json; do not accept lockfile-only transitive rewrites.
• Run pnpm check-all and local Huly integration tests before treating an SDK upgrade as viable.

Available Tools

TOOLSETS categories: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, associations, activity, notifications, workspace, boards, cards, collaborators, custom-fields, drive, inventory, labels, leads, templates, planner, processes, recruiting, sdk-discovery, spaces, tag-categories, tags, task-management, test-management, user-statuses, virtual-office

Projects

Issues

Comments

Milestones

Documents

Storage

Attachments

Contacts

Documentation truncated — see the full README on GitHub.