hitl-mcp
This server lets an agent send notifications and ask short questions to a human via Slack, WhatsApp, or a fake channel, without persisting anything.
Send one-way notifications (
notify_human) that do not wait for a response.Ask a question (
ask_human) and wait for a brief reply, with an optional timeout (default 5 minutes).Override the target per call by specifying a channel (
fake,slack,whatsapp) and a target ID.Nothing is persisted; all interactions are ephemeral.
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., "@hitl-mcp Ask a human for approval before deploying to production"
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.
hitl-mcp
Stay aware of what your agent is doing. Get pinged for tiny decisions. Go back to the chat when something bigger needs you.
HITL-MCP is an ephemeral communication bridge between an AI agent execution and a human channel you already use (Slack, …).
It is not a task manager, messaging platform, SaaS product, centralized gateway, or agent orchestration system.
The agent owns its own task state and context. HITL only delivers progress and short questions.
Vision
Agent starts work → notify_human ("Started …")
Agent makes progress → notify_human (milestones)
Small, quick choice → ask_human (brief channel reply)
Something important
/ long to read → notify_human ("Open the agent chat to reply")
Agent finishes → notify_human ("Done …")Situation | Tool | Where you respond |
Progress from start → finish |
| Nowhere (FYI only) |
Tiny question (yes/no, A/B, one line) |
| In the channel thread |
Important / long / needs context |
| In the agent chat |
HITL is awareness + triage — not a second inbox for deep conversations.
Related MCP server: WhatsApp MCP
Core idea
AGENT
↓
MCP stdio
↓
HITL Core
↓
Channel Adapter
↓
Slack / WhatsApp / …
↓
HumanNothing about the interaction is stored by HITL. Pending asks live in memory only and disappear when the process exits.
Principles
Principle | Meaning |
Local-first | The MCP runs on your machine |
stdio MVP | No HTTP server for event delivery |
No central backend | No HITL cloud, no shared gateway |
No HITL account | No email, password, or centralized identity |
No task database | Agents keep their own state |
Ephemeral pending requests | In memory only; gone when the process exits |
User-owned providers | Your Slack app / your WhatsApp session |
Persistent config only | Named targets + default + provider prefs locally; project |
Credentials separated | Tokens/sessions stored apart from runtime state |
Per-call / per-chat overrides | Explicit |
Architectural rule: if a feature requires HITL to remember something after the current agent execution ends, that feature probably does not belong here.
MCP tools
Exactly three:
notify_human
One-way update. Use for:
start / progress / done
“Something needs you in the agent chat — open it to reply”
Soft-skips when HITL is disabled for the chat (/hitl.off).
ask_human
Short question; waits for a brief channel reply (confirm, pick an option, one line). Soft-skips when disabled.
configure_hitl
Per-chat prefs. Call when the user types /hitl.off, /hitl.on, or /hitl-channel.<channel> (e.g. /hitl-channel.slack).
Optional label sets the channel thread title. On Slack, the first call opens a thread; later calls stay in it.
Quick start
npm install
npm run build
# Configure Slack, WhatsApp, or Fake for local testing
npm run setup
# or: node dist/index.js setup
# Run the MCP server (stdio)
npm startSlack (Socket Mode)
Create a Slack App with Socket Mode enabled
Add bot scopes and
message.channels/message.groupseventsInstall the app, copy
xoxb-andxapp-tokensInvite the bot to your HITL channel
Run
hitl-mcp setup→ choose Slack
Full walkthrough: docs/slack.md
WhatsApp (local session)
Run
hitl-mcp setup→ choose WhatsAppLink via QR (or pairing code) in WhatsApp → Linked Devices
Pick a default chat/group (or paste a JID)
Uses an unofficial client library — see warnings in docs/whatsapp.md.
MCP client config
{
"mcpServers": {
"hitl": {
"command": "node",
"args": ["/absolute/path/to/hitl-mcp/dist/index.js"],
"env": {
"HITL_PROJECT_ROOT": "${workspaceFolder}"
}
}
}
}Status
Channel | Status |
Fake | Working (tests / local dev) |
Slack (Socket Mode) | Working |
WhatsApp (Baileys) | Working |
Documentation
Optional agent guidance: agent-rules/HITL.md
Non-goals
No task management, databases, REST API, web dashboard, user accounts, or conversation history.
License
MIT
Available Tools
2 toolsask_humanA
Send a question to the human via their configured communication channel and wait for a reply. Uses the default target unless an explicit target override is provided. Nothing is persisted.
Inputs: question (required), target, timeoutMs.
notify_humanA
Send a one-way notification to the human. Does not wait for a response. Nothing is persisted.
Inputs: message (required), target.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
ask_human and notify_human serve clearly distinct purposes: one requests a reply, the other sends a notification without waiting. There is no overlap or ambiguity in their intent.
Both tool names follow the same verb_noun pattern, with the target 'human' consistently placed as the object. The naming is clear, predictable, and easy to pattern-match.
Two tools is slightly below the typical 3-15 range, but the server's scope is narrow and both tools earn their place. The count feels slightly minimal but not inadequate for a basic HITL utility.
The tool surface covers the two core human-in-the-loop modes: interactive question-answering and one-way notification. Minor gaps like persistence or cancellation are absent, but they are not clearly implied by the stated purpose.
Maintenance
Related MCP Connectors
Give any AI agent a way to ask a person — for approval, a decision, an answer or a review.
Let your AI agents ask you for decisions and get your answers back, from your phone or the web.
Zero-setup WhatsApp notifications + human-in-the-loop for AI agents — text 'join', send in 60s.
Human approvals, notifications, inbound webhooks, wake-ups for headless agents. Free trial: /try
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to request user decisions and send notifications via Discord when human intervention is required during autonomous tasks. It supports blocking questions with custom options, progress reporting, and persistent state for seamless remote task management.8MIT
- AlicenseNot gradedqualityDmaintenanceHuman-in-the-loop approvals and notifications for AI agents via WhatsApp. Enables Cursor, Claude Code, and autonomous AI agents to reach users away from their computers.112 npmISC
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to request information and clarification from humans via Slack, supporting multiple roles and transport modes.-
- AlicenseAqualityCmaintenanceWhatsApp notifications and human-in-the-loop for AI agents. Text "join" to get an API key, then send messages, ask questions with tap-to-answer buttons, and read replies - no Meta account, no templates, no dashboard.525 PyPI1MIT