@agilex/huly-recruit-mcp

MCP Server Specification for the Huly Recruit Module

1. Overview

A Model Context Protocol server that exposes Huly Recruit operations as tools any MCP-compatible client can call. It wraps @hcengineering/api-client and lets AI agents create and manage talents, vacancies, applications, and pipeline movements without touching the Huly UI.

What this is

• The first MCP server for Huly's Recruit (ATS) module
• Exposes recruitment operations as MCP tools over stdio transport
• Compatible with Claude Code, Claude Desktop, Cursor, and any MCP client
• Connects to Huly via @hcengineering/api-client (WebSocket)
• Follows "Path B" architecture — Huly stores metadata + links; durable artifacts (CVs, briefs) live in Google Workspace

What this is not

• Not a Huly Tracker (issues/projects) server — see kwhittenberger/huly-mcp-server for that
• Not a general-purpose Huly admin tool
• Not a legacy ATS migration tool (yet)

2. Connection & Authentication

Transport

MCP over stdio (standard input/output). The server is a Node.js process that communicates with the MCP client via JSON-RPC 2.0 on stdin/stdout.

Huly Authentication

The server authenticates to Huly using email/password credentials via @hcengineering/api-client, which establishes a WebSocket connection with a NodeWebSocketFactory.

Environment Variables

MCP Client Configuration

{
  "mcpServers": {
    "huly-recruit": {
      "command": "npx",
      "args": ["-y", "@agilex/huly-recruit-mcp"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "…",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

3. Tools

{
  "talent_id": "69eda41502dd3b119a5c8fda",  // Huly Person doc ref
  "name": "Kagiso Maile",
  "channels_added": 6,                       // email + phone + linkedin + 3 drive URLs
  "warnings": []                             // or ["skills (5) accepted but not attached…"]
}

{
  "vacancy_id": "69f1a89d02dd3b119a5c9012",
  "name": "V3 · ML Platform Engineer (LLM/MLOps)"
}

{
  "application_id": "69f1b23402dd3b119a5c9045",
  "talent_id": "69eda41502dd3b119a5c8fda",
  "vacancy_id": "69f1a89d02dd3b119a5c9012",
  "stage": "HR Interview"
}

4. Roadmap Tools

5. Huly Data Model Reference

Entity Relationships

Person (contact:class:Person)
  ├── recruit:mixin:Candidate    ← makes it a Talent
  ├── Channel[] (Email, Phone, LinkedIn, Homepage)
  └── Application[] (one per Vacancy)

Vacancy (recruit:class:Vacancy extends task:class:Project)
  ├── statuses[] (7 default pipeline stages)
  ├── members[], owners[]
  └── Applicant[] (one per Talent applied)

Applicant (recruit:class:Applicant)
  ├── space = Vacancy (Vacancy IS a Space)
  ├── attachedTo = Person (Talent)
  ├── status = pipeline stage ref
  └── assignee = Employee ref (optional)

Wire-Verified Class References

Verified 2026-04-26 against Huly hcengineering/platform main branch and confirmed via wire probes against a live workspace.

6. Path B — Document Storage Architecture

The MCP server follows "Path B": Huly stores metadata and links only. Durable artifacts (CVs, briefs, scorecards, contracts) live in Google Workspace.

Drive URLs are stored as Homepage channels on the Person — the same mechanism a recruiter uses when pasting a link through the Huly UI. This ensures agents stay within capability parity with human users.

7. Seed Script

The repository includes a seed script that populates a complete demo workspace in ~12 seconds:

npm run seed:v3-demo

Creates:

• 1 Vacancy: "V3 · ML Platform Engineer (LLM/MLOps)" — R1.4M–R1.8M CTC, Cape Town hybrid
• 5 Talents with full profiles, channels, and Drive URL references
• 5 Applications — one per pipeline stage (Backlog through Offer)

Result: a fully populated Kanban board in Huly Recruit → Vacancies → V3.

8. Setup & Development

Prerequisites

• Node.js 22.12.0+ (.nvmrc included)
• A Huly account with Recruit module access

Install & Run

git clone https://github.com/craig-agilex/huly-recruit-mcp.git
cd huly-recruit-mcp
npm install
cp .env.example .env.local  # fill in HULY_EMAIL, HULY_PASSWORD, HULY_WORKSPACE
npm run dev                  # starts MCP server on stdio

Test Individual Tools

npm run test:create-talent
npm run test:create-vacancy
npm run test:create-application
npm run seed:v3-demo          # full demo seed

Build

npm run build                # → dist/index.mjs (ESM, Node 22 target)

9. Technical Details

Known Limitations (v0.0.1)

• Skills: Accepted as input but not attached — requires the @hcengineering/tags subsystem (deferred)
• Deduplication: create_talent always creates a new Person. find_talent (Phase 3) is needed to check for existing records first.
• WebSocket only: @hcengineering/api-client uses WebSocket, which doesn't run in Cloudflare Workers. For edge integration, a thin HTTP wrapper service is needed.
• CJS import workaround: The api-client is CJS-only; uses createRequire to load from ESM.

@agilex/huly-recruit-mcp · v0.0.1 · GitHub · AgileX · May 2026