@humsana/mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@humsana/mcp-server What's my current state?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@humsana/mcp-server
Cognitive Security for AI-assisted development.
🛡️ "The breathalyzer for your terminal."
Humsana prevents you from running dangerous commands or accepting large AI code rewrites when you're fatigued. Think of it as an industrial safety interlock, but for your brain.
What It Does
Command Protection (safe_execute_command)
Situation | Result |
You're fresh, running | ✅ Runs normally |
You're fresh, running | ⚠️ Warning, allowed |
You're tired, running | ⛔ BLOCKED — requires override |
AI Rewrite Protection (safe_write_file)
Situation | Result |
AI writes new file | ✅ Allowed |
AI rewrites 10 lines | ✅ Allowed |
You're tired + AI deletes 30+ lines | ⚠️ Warning |
You're tired + AI deletes 50+ lines | ⛔ BLOCKED — saved for review |
Related MCP server: FlowCheck MCP Server
Quick Start
1. Install the Daemon
pip install humsana-daemon
humsana startKeep this running in a terminal tab.
2. Install the MCP Server
npm install -g @humsana/mcp-server3. Configure Claude Desktop
Create/edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"humsana": {
"command": "node",
"args": ["/path/to/humsana-mcp/dist/index.js"]
}
}
}4. Restart Claude Desktop
Quit (Cmd+Q) and reopen.
5. Test It
Ask Claude: "What's my current state?"
Execution Modes
Humsana starts in dry-run mode for safety. Commands are simulated, not executed.
Dry-Run Mode (Default)
✅ [DRY RUN] Safety check passed.
Command: `kubectl delete pods`
This command WOULD have been executed.
(Execution skipped: dry_run mode active)Switching to Live Mode
When you trust the system, enable real execution:
Step 1: Create/edit ~/.humsana/config.yaml:
# Change this from 'dry_run' to 'live'
execution_mode: live
# Optional: adjust thresholds
fatigue_threshold: 70
write_warn_threshold: 30
write_block_threshold: 50Step 2: Restart Claude Desktop (Cmd+Q, reopen)
Step 3: Test with a safe command first:
Run `echo "live mode working"`You should see actual output instead of "WOULD have been executed."
Configuration Reference
Create ~/.humsana/config.yaml:
# === EXECUTION MODE ===
# 'dry_run' (default) - Simulates commands, nothing executed
# 'live' - Actually executes commands and writes files
execution_mode: dry_run
# === FATIGUE THRESHOLDS ===
# Fatigue level (0-100) above which dangerous commands are blocked
fatigue_threshold: 70
# Lines removed to trigger warning (when fatigued)
write_warn_threshold: 30
# Lines removed to trigger hard block (when fatigued)
write_block_threshold: 50
# === CUSTOM PATTERNS ===
# Additional dangerous commands to block
deny_patterns:
- "aws ec2 terminate"
- "docker rm -f"
# === NOTIFICATIONS ===
# Webhook for Slack/PagerDuty (fires on safety overrides)
webhook_url: https://hooks.slack.com/services/XXX/YYY/ZZZOverride Protocol
When blocked, say:
OVERRIDE SAFETY PROTOCOL: [reason]Example:
OVERRIDE SAFETY PROTOCOL: P0 production outage, need to restart podsThis is logged to ~/.humsana/audit.json and sent to your webhook.
Tools Available
Tool | Purpose |
| Get current stress, focus, fatigue levels |
| Check if a command would be blocked |
| Execute shell commands with interlock |
| Write files with AI rewrite protection |
Files & Folders
Path | Purpose |
| Behavioral data from daemon |
| Your configuration |
| Activity heartbeats (for fatigue) |
| Safety event log |
| Blocked AI writes saved here |
Privacy
🔒 100% Local.
All data stays on your machine
No network calls (except optional webhook)
No telemetry, no tracking
Fully auditable open-source code
Troubleshooting
"Daemon not running" error
Start the daemon in a terminal:
humsana startCommands not executing
Check your mode:
cat ~/.humsana/config.yaml | grep execution_modeIf it says dry_run, change to live and restart Claude.
MCP not connecting
Verify your Claude Desktop config path:
Mac:
~/Library/Application Support/Claude/claude_desktop_config.jsonEnsure the path to
dist/index.jsis correct
License
MIT
Available Tools
4 toolshumsana_check_dangerous_commandA
Check if a command is dangerous and whether the user is too fatigued to safely run it. Use this before helping with potentially destructive operations like rm -rf, DROP TABLE, git push --force, kubectl delete, terraform destroy, etc.
Inputs: command (required).
humsana_get_user_stateA
Get the user's current behavioral state including stress level, focus level, fatigue, and response style recommendations. Use this at the start of conversations to adapt your communication style.
Inputs: no named parameters.
humsana_safe_execute_commandA
Execute a shell command with Humsana Cognitive Interlock protection. This is THE tool for running commands - it blocks dangerous commands when the user is fatigued, requires override confirmation for high-risk operations, and logs all safety events. Use this instead of any other shell/bash tool.
Inputs: command (required), override_reason.
humsana_safe_write_fileA
Write content to a file with Humsana Cognitive Interlock protection. This tool prevents AI from making large destructive rewrites when the user is fatigued. If AI tries to delete/rewrite >30 lines while user is tired, it blocks the write and saves to a review folder. Use this for ALL file write operations.
Inputs: content (required), filepath (required), override_reason.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: retrieving user state, checking command risk, executing commands with protection, and writing files with protection. No overlap or ambiguity between them.
All tools follow a consistent 'humsana_' prefix with a verb_noun pattern: get_user_state, check_dangerous_command, safe_execute_command, safe_write_file. Naming is uniform and predictable.
The server has 4 tools, a well-scoped set for its stated purpose of providing safety-aware operations. Each tool is essential and there is no bloat or missing trivial add-ons.
The surface covers the core lifecycle: state check, pre-flight risk check, command execution, and file writes. Minor gaps exist such as no dedicated safe delete/read tools, but these can be worked around via safe_execute_command.
Maintenance
Related MCP Connectors
Guardian agent for AI coding: four frontier models review risky diffs and commits before they ship.
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
AI code governance and code review for Claude Code, Copilot and Cursor. Checks rules and security.
Apiiro Application Security Posture Management (ASPM) tools for AI coding assistants.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides real-time security risk assessment for AI coding prompts, analyzing potential dangers, blast radius, and complexity before code execution in Cursor.1MIT
- AlicenseAqualityDmaintenanceActs as a production-grade safety layer for AI-assisted coding, monitoring Git hygiene, scanning for security issues (PII, secrets, injection), and enabling semantic history search.9MIT
- AlicenseNot gradedqualityCmaintenanceA runtime gate for coding agents. Blocks the tool calls that wreck a repo (force-push main, rm -rf, secret exfiltration, CI wipe) and lets normal build and commit work through. Machine-checked git-branch core (z3); the rest is high-precision heuristics. Tested on 3,790 real CI commands, 0 false blocks.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI-powered security scanning of code changes and files through coding assistants, detecting vulnerabilities and providing fixes.1MIT