ask-user-questions-mcp

paulp-o/ask-user-questions-mcp

3.4

If you are the rightful owner of ask-user-questions-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

AUQ is a lightweight MCP server and CLI tool designed to facilitate interaction between LLMs and users by allowing AI to ask clarifying questions in a separate terminal interface.

AUQ - Ask User Questions

npm version License: MIT Install MCP Server

A lightweight CLI tool that allows your LLMs to ask questions to you in a separate space with clean terminal UX. Supports both MCP server and official OpenCode plugin integration. Made for multi-agent parallel coding workflows.

🤔 Why do I need it when I already have question tool in CC/OC?

Setup • Features

What does it do?

AUQ lets your AI assistants generate clarifying questions consisting of multiple-choice/single-choice questions (with an "Other" option for custom input) while coding or working, and wait for your answers through a separate CLI tool without messing up your workflow.

You can keep the CLI running in advance, or start it when questions are pending. With simple arrow key navigation, you can select answers and send them back to the AI—all within a clean terminal interface.

Background

In AI-assisted coding, guiding LLMs to ask clarifying questions have been widely recognized as a powerful prompt engineering technique to overcome LLM hallucination and generate more contextually appropriate code [1].

On October 18th, Claude Code 2.0.21 introduced an internal ask-user-question tool. Inspired by it, I decided to build a similar tool that is:

  • Integration-flexible - Works with MCP clients (Claude Desktop, Cursor, etc.) and has official OpenCode plugin support
  • Non-invasive - Doesn't heavily integrate with your coding CLI workflow or occupy UI space
  • Multi-agent friendly - Supports receiving questions from multiple agents simultaneously in parallel workflows

✨ Features

https://github.com/user-attachments/assets/3a135a13-fcb1-4795-9a6b-f426fa079674

🖥️ CLI-Based

  • Lightweight: Adds only ~150 tokens to your context per question
  • SSH-compatible: Use over remote connections
  • Fast: Instant startup, minimal resource usage

📦 100% Local

All information operates based on your local file system. No data leaves your machine.

🔄 Resumable & Stateless

The CLI app doesn't need to be running in advance. Whether the model calls the MCP first and you start the CLI later, or you keep it running—you can immediately answer pending questions in FIFO order.

❌ Question Set Rejection with Feedback Loop

When the LLM asks about the wrong domain entirely, you can reject the question set, optionally providing the reason to the LLM. The rejection feedback is sent back to the LLM, allowing it to ask more helpful questions or align on what's important for the project.

📋 Question Set Queuing

Recent AI workflows often use parallel sub-agents for concurrent coding. AUQ handles multiple simultaneous LLM calls gracefully—when a new question set arrives while you're answering another, it's queued and processed sequentially. Perfect for multi-agent parallel coding workflows.

🤔 Why AUQ vs. Built-in Ask Tools?

Why should I use AUQ instead of the built-in "Question" tools in OpenCode, Claude Code, or other coding agents?

AUQ is designed for the era of parallel multi-agent workflows, with several key advantages:

🚀 Non-Blocking Parallel Operation

Unlike built-in ask tools that halt the entire AI workflow until you respond, AUQ doesn't block the AI from continuing work. Questions are queued asynchronously, allowing your AI assistants to keep coding while you review and answer questions at your own pace.

🎯 Multi-Agent Question Set Support

The killer feature: AUQ can handle question sets from multiple agents simultaneously. In modern AI coding workflows, you often have several sub-agents working in parallel—each might need clarification on different aspects of your codebase. With AUQ:

  • No more screen switching between different agent conversations
  • Unified queue for all agent questions, regardless of which AI tool they're coming from
  • Sequential processing of questions from multiple sources in one interface

🌐 Cross-Platform Question Aggregation

AUQ's unified data origin means you can answer questions from different AI clients simultaneously:

  • Claude Code questions
  • OpenCode questions
  • Cursor/MCP questions

All appear in the same CLI interface, creating a single source of truth for all AI-agent questions across your entire development environment.

💡 Perfect for Parallel Agent Workflows

As AI coding moves toward sophisticated multi-agent systems, AUQ becomes essential. Instead of managing blocking questions across multiple agent screens, you get one streamlined interface that handles questions from your entire AI coding ecosystem—keeping your focus on the code, not the coordination.

TL;DR: AUQ transforms AI-agent questions from blocking interruptions into a smooth, unified workflow that scales with your AI coding setup.

Setup Instructions

🚀 Install CLI Tool

First, install the AUQ CLI tool:

Global Installation (Recommended)

# Install globally
npm install -g auq-mcp-server

# Start the TUI
auq

Local Installation (Project-specific)

# Install in your project
npm install auq-mcp-server

# Start the TUI from project directory
npx auq

Session Storage:

  • Global install: ~/Library/Application Support/auq/sessions (macOS), ~/.local/share/auq/sessions (Linux)
  • Local install: .auq/sessions/ in your project root

🔌 Choose Your Integration Method

AUQ supports multiple AI coding environments. Choose the one that fits your workflow:

Option A: MCP Server (Recommended for most users)

Cursor

Install MCP Server

Claude Code (CLI)

Method 1: Using CLI (Recommended)

claude mcp add --transport stdio ask-user-questions -- npx -y auq-mcp-server server

Method 2: Manual Configuration

Add to .mcp.json in your project root (for team-wide sharing):

{
  "mcpServers": {
    "ask-user-questions": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "auq-mcp-server", "server"]
    }
  }
}

Or add to ~/.claude.json for global access across all projects.

Verify setup: Type /mcp in Claude Code to check server status.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.ask-user-questions]
command = "npx"
args = ["-y", "auq-mcp-server", "server"]

Full configuration example (with optional settings):

[mcp_servers.ask-user-questions]
command = "npx"
args = ["-y", "auq-mcp-server", "server"]

# Optional: Additional environment variables
# env = { "AUQ_SESSION_DIR" = "/custom/path" }

# Optional: Whitelist additional env vars
# env_vars = ["AUQ_SESSION_DIR"]


# Optional: Working directory
# cwd = "/Users/<user>/projects"

Restart Codex CLI after saving the configuration.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ask-user-questions": {
      "command": "npx",
      "args": ["-y", "auq-mcp-server", "server"]
    }
  }
}

Restart Claude Desktop after saving.

Option B: Official OpenCode Plugin

We now have official OpenCode plugin support! We support OpenCode because OpenCode's MCP server seems to have some limitations (timeout), so we created an OpenCode-specific plugin that works perfectly together with OpenCode.

The OpenCode plugin allows OpenCode to call auq ask directly (without MCP), providing seamless integration with OpenCode's workflow.

Installation
# Install both CLI and plugin
npm install -g auq-mcp-server
npm install -g @paulp-o/opencode-auq
Configuration

Add to opencode.json:

{
  "plugin": ["@paulp-o/opencode-auq"]
}

💻 Usage

Starting the CLI tool

auq  # if you installed globally
npx auq  # if you installed locally

Then just start working with your coding agent or AI assistant. You may prompt to ask questions with the tool the agent got; it will mostly just get what you mean.

Commands

# you won't likely need these at all
auq server       # Start MCP server
auq --version    # Show version
auq --help       # Show help

Manual session cleanup

Sessions auto-clean after completion or timeout. However, you can manually clean them up if you want to.

# Global install
rm -rf ~/Library/Application\ Support/auq/sessions/*  # macOS
rm -rf ~/.local/share/auq/sessions/*                  # Linux

# Local install
rm -rf .auq/sessions/*

🚀 Roadmap

  • Light & dark mode themes
  • MCP prompt mode switch (Anthropic style / minimal)
  • Custom color themes
  • Multi-language support
  • Audio notifications on new question
  • Simple option to prompt the LLM to/not ask more questions after answering.
  • Optional 'context' field privided by the LLM, that describes the context of the questions - will be useful for multi-agent coding

📄 License

MIT License - see file for details.

[1] arXiv:2308.13507 https://arxiv.org/abs/2308.13507