Ask Human MCP server

Ask-Human MCP serves as a simple server that prevents AI hallucinations by giving AI agents a way to ask human questions when they're unsure, rather than making incorrect assumptions. This solution acts like an "escape hatch" for your AI, allowing it to request clarification instead of proceeding with false confidence.

Installation

Installing Ask-Human MCP is straightforward:

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

Then configure your AI client by creating or modifying the MCP configuration file. For Cursor, edit .cursor/mcp.json:

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

After configuration, restart your AI client (like Cursor) to enable the connection.

How It Works

Ask-Human MCP facilitates a simple question-answer workflow:

1. When your AI gets stuck, it calls ask_human(question, context)
2. The question appears in ask_human.md with a unique ID
3. You replace "PENDING" with your answer
4. The AI receives your response and continues working

Sample Question Format

Questions appear in the markdown file with this structure:

### 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 edit the file to provide an answer:

answer: POST /api/v2/auth/login

Once saved, the AI immediately receives your response and continues.

Configuration Options

While Ask-Human MCP works with zero configuration, you can customize its behavior:

Command Line Options

ask-human-mcp --help
ask-human-mcp --port 3000 --host 0.0.0.0  # Run in HTTP mode
ask-human-mcp --timeout 1800              # Set 30-minute timeout
ask-human-mcp --file custom_qa.md         # Use custom Q&A file
ask-human-mcp --max-pending 50            # Limit concurrent questions
ask-human-mcp --max-question-length 5000  # Limit question size
ask-human-mcp --rotation-size 10485760    # Rotate file at 10MB

Client Configuration

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

API Usage

Basic Question

Ask a question and wait for a human response:

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

Additional Functions

The API also provides these utilities:

# Get list of questions waiting for answers
pending_questions = list_pending_questions()

# Get statistics about the Q&A session
stats = get_qa_stats()

System Limits

Ask-Human MCP includes sensible defaults to prevent issues:

Resource	Default Limit	Description
Question length	10KB	Maximum characters per question
Context length	50KB	Maximum characters per context
Pending questions	100	Maximum concurrent questions
File size	100MB	Maximum ask file size
Rotation size	50MB	Size at which files are archived

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "ask-human" '{"command":"ask-human-mcp"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect