Ask Human

The ask-human MCP server solves one of the most frustrating problems in AI development: false confidence and hallucinations.

Instead of your AI making up endpoints, APIs, or implementation details, this server gives it a direct line to ask you questions when it’s genuinely uncertain.

Features

• 🚀 Zero Configuration Setup – Install and run with a single command
• 📝 Markdown Q&A Interface – Questions appear in a simple markdown file you can edit
• ⚡ Real-time File Watching – Instant feedback when you provide answers
• 🔄 Multi-Agent Support – Handle questions from multiple AI instances simultaneously
• 🔒 Built-in Safety Limits – Prevents system overload with configurable timeouts and size limits
• 📊 Persistent History – Complete Q&A logs for debugging and reference
• 🌐 Cross-Platform Compatibility – Works on Windows, macOS, and Linux
• 🔧 Flexible Configuration – Customizable timeouts, file paths, and resource limits
• 🛡️ Security Features – Input sanitization, file locking, and secure permissions

How to Use It

1. Installation

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

2. Configure your MCP Clients

Cursor

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

Claude Desktop

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

HTTP Mode (for remote access):

ask-human-mcp --port 3000 --host 0.0.0.0

Then configure your MCP client:

{
  "mcpServers": {
    "ask-human": {
      "url": "http://localhost:3000/sse"
    }
  }
}

3. Basic Workflow

• AI encounters uncertainty – Instead of guessing, it calls ask_human(question, context)
• Question appears in file – Check ask_human.md for new questions with unique IDs
• You provide the answer – Replace “PENDING” with your response
• AI continues – Receives your answer and proceeds with accurate information

4. Sample Q&A Format

When your AI asks a question, it appears like this in ask_human.md:

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

You simply replace the “PENDING” with your answer:

answer: POST /api/v2/auth/login

5. Command Line Options

ask-human-mcp --help                        # Show all options
ask-human-mcp --port 3000 --host 0.0.0.0   # HTTP mode
ask-human-mcp --timeout 1800                # 30-minute 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

6. Advanced Configuration

{
  "mcpServers": {
    "ask-human": {
      "command": "ask-human-mcp",
      "args": ["--timeout", "900", "--max-pending", "25"]
    }
  }
}

7. Available API Methods

• ask_human(question, context="") – Ask a question and wait for response
• list_pending_questions() – Get all questions awaiting answers
• get_qa_stats() – Retrieve statistics about the current Q&A session

8. Resource Limits

FAQs

Q: What happens if I don’t answer a question?
A: Questions have configurable timeouts (default 10 minutes). After timeout, the AI receives a timeout message and can either retry or handle the situation gracefully.

Q: Can multiple AI agents use this simultaneously?
A: Yes, the server handles concurrent questions from multiple agents. Each question gets a unique ID and file locking prevents conflicts.

Q: Where are the Q&A files stored?
A: By default, ask_human.md is created in your current working directory. You can specify a custom path with the --file option.

Q: How do I handle sensitive information in questions?
A: The server includes input sanitization and creates files with restricted permissions. For extra security, use custom file paths in secure directories.

Q: Can I run this on a remote server?
A: Yes, use HTTP mode with --host 0.0.0.0 --port 3000 and configure your MCP client to connect via the HTTP endpoint.