Ask Human MCP

🚀 ask - human mcp 🧑‍💻🤝🤖

Stop your AI from hallucinating. It provides an escape route for the AI when it's confused, rather than letting it show false confidence.

🚀 Quick Start

30 - sec setup

pip install ask-human-mcp
ask-human-mcp

.cursor/mcp.json:

{
  "mcpServers": {
    "ask-human": { "command": "ask-human-mcp" }
  }
}

Restart Cursor and enjoy.

✨ Features

Solving the Pain Points

AI often blurts out non - existent endpoints or makes unfounded assumptions with false confidence. With ask - human mcp, you can avoid spending time debugging these false - confidence issues.

The Fix

It provides an MCP server that allows the AI agent to "raise its hand" instead of hallucinating. The process is as follows:

1. The agent calls ask_human().
2. The question lands in ask_human.md.
3. You replace "PENDING" with the answer.
4. The agent continues coding.

Sample File

### Q8c4f1e2a
ts: 2025-01-15 14:30  
q: which auth endpoint do we use?  
ctx: building login form in auth.js  
answer: PENDING

You can simply drop:

answer: POST /api/v2/auth/login

Then the flow continues and hopefully, the issues are solved.

Advantages

• Easy Installation: pip install ask - human - mcp and you're done.
• Zero Config, Cross - Platform: No need for complex configurations and works across different platforms.
• Instant Feedback: Watches the file and provides instant feedback.
• Multiple Agents Support: Handles multiple agents without any hassle.
• Safety Mechanisms: Locks and limits are in place to prevent any disasters.
• Markdown Q&A History: Keeps a full Q&A history in Markdown, which is great for debugging.

📦 Installation

pip install ask-human-mcp

💻 Usage Examples

Basic Usage

answer = await ask_human(
    "what database should i use for this project?",
    "building a chat app with 1000+ concurrent users"
)

Other Tools

• list_pending_questions(): Get questions waiting for answers.
• get_qa_stats(): Get stats about the Q&A session.

📚 Documentation

Config Options

Command Line

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 10mb

Different Clients

Cursor (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"
    }
  }
}

What's in the Box

• Zero Configuration: Works out of the box.
• File Watching: Provides instant response when you save answers.
• Timeout Handling: Ensures questions don't hang forever.
• Concurrent Questions: Handles multiple AI agents.
• Persistent Logging: Keeps a full Q&A history in Markdown.
• Cross - Platform: Supports Windows, macOS, and Linux.
• MCP Standard: Works with any MCP client.
• Input Validation: Has size limits and sanitization.
• File Rotation: Automatically archives large files.
• Resource Limits: Prevents DOS and memory leaks.
• Robust Parsing: Handles malformed Markdown gracefully.

Security Stuff

• Input Sanitization: Removes control characters and validates sizes.
• File Locking: Prevents corruption from concurrent access.
• Secure Permissions: Files are created with restricted access.
• Resource Limits: Prevents memory exhaustion and DOS attacks.
• Path Validation: Ensures files are written to safe locations.

Limits

Platform Support

• Windows: Full support with native file locking.
• macOS: Full support with fsevents file watching.
• Linux: Full support with inotify file watching.

🔧 Technical Details

How it Works

1. The AI gets stuck and calls ask_human(question, context).
2. The question is logged and appears in ask_human.md with a unique ID.
3. The human answers by replacing "PENDING" with the response.
4. The AI continues and uses the answer to proceed.

Development

From Source

git clone https://github.com/masonyarbrough/ask-human-mcp.git
cd ask-human-mcp
pip install -e ".[dev]"
ask-human-mcp

Tests

pytest tests/ -v

Code Quality

black ask_human_mcp tests
ruff check ask_human_mcp tests  
mypy ask_human_mcp

Contributing

We would love to have any contributors.

Issues

Use the GitHub issue tracker to report bugs or request features. You can also email me at mason@kallro.com.

Please include:

• Python version
• Operating system
• MCP client (Cursor, Claude desktop, etc.)
• Error messages or logs
• Steps to reproduce

Changelog

See CHANGELOG.md for version history.

📄 License

This project is under the MIT license. See LICENSE file for details.

Thanks

• model context protocol for the excellent standard.
• anthropic for Claude and MCP support.
• cursor for MCP integration.
• All contributors and users providing feedback.