stop your ai from hallucinating. gives it an escape route when confused instead of false confidence.
ai blurts out an endpoint that never existed
the agent makes assumptions that are simply not true and has false confidence
repeat x100 errors and your day is spent debugging false confidence and issues when you could simply ask a question
an mcp server that lets the agent raise its hand instead of hallucinating. feels like mentoring a sharp intern who actually asks before guessing.
agent → ask_human()
⬇
question lands in ask_human.md
⬇
you swap "PENDING" for the answer
⬇
agent keeps coding
### Q8c4f1e2a
ts: 2025-01-15 14:30
q: which auth endpoint do we use?
ctx: building login form in auth.js
answer: PENDINGyou drop:
answer: POST /api/v2/auth/loginboom. flow continues and hopefully the issues are solved.
- pip install ask-human-mcp → done
- zero config, cross-platform
- watches the file, instant feedback
- multiple agents, no sweat
- locks + limits so nothing catches fire
- full q&a history in markdown (nice paper-trail for debugging)
pip install ask-human-mcp
ask-human-mcp.cursor/mcp.json:
{
"mcpServers": {
"ask-human": { "command": "ask-human-mcp" }
}
}restart cursor and vibe.
- ai gets stuck → calls
ask_human(question, context) - question logged → appears in
ask_human.mdwith unique ID - human answers → replace "PENDING" with your response
- ai continues → uses your answer to proceed
the ai receives your answer and keeps coding!
ask-human-mcp --help
ask-human-mcp --port 3000 --host 0.0.0.0 # http mode
ask-human-mcp --timeout 1800 # 30min timeout
ask-human-mcp --file custom_qa.md # custom q&a file
ask-human-mcp --max-pending 50 # max concurrent questions
ask-human-mcp --max-question-length 5000 # max question size
ask-human-mcp --rotation-size 10485760 # rotate file at 10mbcursor (local):
{
"mcpServers": {
"ask-human": {
"command": "ask-human-mcp",
"args": ["--timeout", "900"]
}
}
}cursor (http):
{
"mcpServers": {
"ask-human": {
"url": "http://localhost:3000/sse"
}
}
}claude desktop:
{
"mcpServers": {
"ask-human": {
"command": "ask-human-mcp"
}
}
}- zero configuration → works out of the box
- file watching → instant response when you save answers
- timeout handling → questions don't hang forever
- concurrent questions → handle multiple ai agents
- persistent logging → full q&a history in markdown
- cross-platform → windows, macos, linux
- mcp standard → works with any mcp client
- input validation → size limits and sanitization
- file rotation → automatic archiving of large files
- resource limits → prevent dos and memory leaks
- robust parsing → handles malformed markdown gracefully
- input sanitization → removes control characters and validates sizes
- file locking → prevents corruption from concurrent access
- secure permissions → files created with restricted access
- resource limits → prevents memory exhaustion and dos attacks
- path validation → ensures files are written to safe locations
| thing | default | what it does |
|---|---|---|
| question length | 10kb | max characters per question |
| context length | 50kb | max characters per context |
| pending questions | 100 | max concurrent questions |
| file size | 100mb | max ask file size |
| rotation size | 50mb | size at which files are archived |
- windows → full support with native file locking
- macos → full support with fsevents file watching
- linux → full support with inotify file watching
ask the human a question and wait for response.
answer = await ask_human(
"what database should i use for this project?",
"building a chat app with 1000+ concurrent users"
)list_pending_questions()→ get questions waiting for answersget_qa_stats()→ get stats about the q&a session
git clone https://github.com/masonyarbrough/ask-human-mcp.git
cd ask-human-mcp
pip install -e ".[dev]"
ask-human-mcppytest tests/ -vblack ask_human_mcp tests
ruff check ask_human_mcp tests
mypy ask_human_mcpwould love any contributors
use the github issue tracker to report bugs or request features.
you can also just email me: mason@kallro.com
include:
- python version
- operating system
- mcp client (cursor, claude desktop, etc.)
- error messages or logs
- steps to reproduce
see CHANGELOG.md for version history.
mit license - see LICENSE file for details.
- model context protocol for the excellent standard
- anthropic for claude and mcp support
- cursor for mcp integration
- all contributors and users providing feedback