Humaans — Claude Code MCP server: features and setup
Connects Humaans to an MCP host so an agent can work with people, roles, time away, offices, and company records. It requires an API key.
claude mcp add mcp-server-humaans -e HUMAANS_API_KEY=<HUMAANS_API_KEY> -- npx -y @mindstone/mcp-server-humaansWhat Humaans does
Humaans exposes the Humaans HR platform through the @mindstone/mcp-server-humaans package and an MCP interface. Its 16 tools cover employee profiles, team listings, job-role history, time-away records, company details, and office locations. An agent can also submit, approve, decline, or cancel time-away requests.
People results use an allowlist, while profile details remove tax IDs, personal contacts, home addresses, birthdays, and profile photos. Free-text values are wrapped in <untrusted-content> so the model handles them as records rather than instructions. The package needs Node.js 20+, npm, and a Humaans access token in HUMAANS_API_KEY.
Without HUMAANS_API_KEY, the server cannot reach Humaans. The published package runs through npx; a local checkout must be built with npm run build before starting its compiled entry point.
What it helps with
- look up an employee profile by ID
- list people and their teams
- submit or cancel time-away requests
- approve or decline a pending absence request
- retrieve company and office details
Example prompts for the agent
- Use
list_humaans_peopleto show the employees and their teams. - Create a time-away request with the supplied dates and reason using
create_humaans_time_away. - Fetch the company record and office list with
get_humaans_companyandlist_humaans_locations.
How to install Humaans
Platform CLI
claude mcp add mcp-server-humaans -e HUMAANS_API_KEY=<HUMAANS_API_KEY> -- npx -y @mindstone/mcp-server-humaansReplace <…> with your own values
Platform CLI
codex mcp add humaans --env HUMAANS_API_KEY=<HUMAANS_API_KEY> -- npx -y @mindstone/mcp-server-humaansReplace <…> with your own values
Config file
{
"mcpServers": {
"humaans": {
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-humaans"
],
"env": {
"HUMAANS_API_KEY": "<HUMAANS_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"humaans": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mindstone/mcp-server-humaans"
],
"env": {
"HUMAANS_API_KEY": "<HUMAANS_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e HUMAANS_API_KEY=<HUMAANS_API_KEY> humaans npx -y @mindstone/mcp-server-humaansReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Humaans
How do I install Humaans in Claude Code?
Run claude mcp add mcp-server-humaans -e HUMAANS_API_KEY=<HUMAANS_API_KEY> -- npx -y @mindstone/mcp-server-humaans. This registers the MCP server and passes the Humaans key to it.
What does Humaans do?
It gives an MCP host tools for Humaans employee profiles, teams, job roles, time-away requests, offices, and company information.
What happens to sensitive profile data?
Detailed profile responses remove tax IDs, personal contact details, home addresses, birthdays, and profile photos. Free-text fields are marked as <untrusted-content> before reaching the model.
