Humaans

@mindstone/mcp-server-humaans

[npm version] [License: FSL-1.1-MIT]

Humaans HR platform MCP server for Model Context Protocol hosts. Query employee profiles, job roles, time-away requests, company info, and office locations through a standardised MCP interface.

Status

• Version: 0.3.1 · npm
• Auth: API key (HUMAANS_API_KEY)
• Tools: 16 (people, job-roles, time-away, company, teams)
• Surface: cloud-api
• Machine-readable: STATUS.json

Requirements

• Node.js 20+
• npm

One-click install

[Add to Cursor] [Add to VS Code] [Add to VS Code Insiders]

After clicking the button, your host will prompt you to fill: HUMAANS_API_KEY.

{  "mcpServers": {    "Humaans": {      "command": "npx",      "args": [        "-y",        "@mindstone/mcp-server-humaans"      ],      "env": {        "HUMAANS_API_KEY": ""      }    }  }}

Quick Start

Install & build

cd <path-to-repo>/connectors/humaansnpm installnpm run build

npx (once published)

npx -y @mindstone/mcp-server-humaans

Local

node dist/index.js

Configuration

Environment variables

• HUMAANS_API_KEY — Humaans API access token (from app settings)
• MCP_HOST_BRIDGE_STATE — optional path to a host bridge state file used for credential management
• MINDSTONE_REBEL_BRIDGE_STATE — backwards-compatible alias for MCP_HOST_BRIDGE_STATE

Host configuration examples

Claude Desktop / Cursor

{  "mcpServers": {    "Humaans": {      "command": "npx",      "args": ["-y", "@mindstone/mcp-server-humaans"],      "env": {        "HUMAANS_API_KEY": "your-api-key"      }    }  }}

Local development (no npm publish needed)

{  "mcpServers": {    "Humaans": {      "command": "node",      "args": ["<path-to-repo>/connectors/humaans/dist/index.js"],      "env": {        "HUMAANS_API_KEY": "your-api-key"      }    }  }}

Tools (16)

Configuration

• configure_humaans_api_key — Configure the Humaans API access token

People

• get_humaans_me — Get the current authenticated user's profile
• list_humaans_people — List employees
• get_humaans_person — Get full employee profile by ID
• list_humaans_teams — List team names with member counts (derived from the people directory; Humaans has no dedicated teams endpoint)

Job roles

• list_humaans_job_roles — List job role history for employees
• get_humaans_job_role — Get a specific job role by ID

Time away

• list_humaans_time_away — List time-away entries (PTO, sick leave, etc.)
• create_humaans_time_away — Create a time-away request
• list_humaans_time_away_types — List available time-away types
• list_humaans_time_away_allocations — List time-away allocations (which policy applies to each person)
• cancel_humaans_time_away — Cancel (permanently delete) a time-away entry
• approve_humaans_time_away — Approve a pending time-away request (manager action)
• decline_humaans_time_away — Decline a pending time-away request (manager action)

Company

• list_humaans_locations — List company locations/offices
• get_humaans_company — Get company information

Data handling

• Person list responses are field-allowlisted; person detail responses strip sensitive fields (tax ID, personal email/phone, home address, birthday, profile photo).
• Free-text fields authored in Humaans (time-away note/reviewNote, job-role note/jobTitle/department, time-away type and policy names, team names, person profile free text such as names/bio/social links/job title, location labels/cities, the company name) are returned inside <untrusted-content> envelopes so the model treats them as data, not instructions.
• Humaans API error bodies are enveloped (and non-JSON bodies capped) before they reach the model; Retry-After reaches rate-limit messages only as a parsed integer, and a malformed 2xx body yields a static error rather than a parser message embedding a body snippet.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.