Human Loop
Browser-based human-in-the-loop MCP server β ask your AI agent to ask you via polished browser dialogs.
Ask AI about Human Loop
Powered by Claude Β· Grounded in docs
I know everything about Human Loop. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
human-loop-mcp
Browser-based human-in-the-loop MCP server
Ask your AI agent to ask you β via polished browser dialogs.
Features Β· Install Β· Quick Start Β· Tools Β· Attachments Β· Configuration Β· Architecture Β· Development
What Is This?
An MCP (Model Context Protocol) server that gives AI agents a way to ask the human operator questions through the browser.
- A lightweight localhost HTTP server spins up
- Your default browser opens a dialog page
- You fill in the form (optionally attaching files) and submit
- The response flows back to the agent through MCP
No Python, no Tkinter, no Electron β just a Node.js process, a browser tab, and clean HTML.
Why?
GUI-based human-in-the-loop tools often break on macOS (Accessibility permissions, focus stealing, Python framework builds). This project sidesteps all of that by using the browser as the UI layer β it works everywhere Node.js runs.
Features
| 7 MCP tools | Text input, multiline, choice, confirmation, info, health check, and usage guidance |
| File attachments | Drag-and-drop, paste, or click-to-upload files in the multiline dialog. Files are base64-encoded and returned alongside the text response (5 MB per-file limit) |
| Autocomplete | @ files, # GitHub issues/PRs, / slash commands, ? keyboard shortcuts |
| Dark/light mode | Follows system preference automatically |
| Keyboard-first | Cmd+Enter submit, Esc cancel, arrow-key navigation in dropdowns |
| Command-palette UI | Linear/Raycast-inspired design with purple accents, monospace labels, noise texture background |
| Zero bloat | Only two runtime dependencies: @modelcontextprotocol/sdk and zod |
| Single-file HTML | No static assets, no bundler β fully server-rendered |
Install
npm (recommended)
npm install -g human-loop-mcp
Or run directly without installing:
npx human-loop-mcp
From source
git clone https://github.com/dzulfiikar/human-loop-mcp.git
cd human-loop-mcp
npm install
npm run build
Quick Start
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"human-loop": {
"command": "npx",
"args": ["-y", "human-loop-mcp"]
}
}
}
Cursor / Windsurf
Add to .cursor/mcp.json or equivalent:
{
"mcpServers": {
"human-loop": {
"command": "npx",
"args": ["-y", "human-loop-mcp"]
}
}
}
GitHub Copilot CLI
[mcp_servers.human-loop]
command = "npx"
args = ["-y", "human-loop-mcp"]
From source (development)
[mcp_servers.human-loop-dev]
command = "npx"
args = ["tsx", "/path/to/human-loop-mcp/src/index.ts"]
Tools
| Tool | Description |
|---|---|
get_user_input | Single-line text, password, integer, or float input |
get_user_choice | Single or multi-select from a list of choices |
get_multiline_input | Large text area with autocomplete and file attachments |
show_confirmation_dialog | Binary confirm/cancel dialog |
show_info_message | Informational message with acknowledgement |
get_human_loop_prompt | Returns guidance text on when to use the tools |
health_check | Returns server health status and available tools |
Example: Text Input
{
"title": "API Key",
"prompt": "Enter your OpenAI API key:",
"input_type": "password"
}
Example: Choice
{
"title": "Database",
"prompt": "Which database should I use?",
"choices": ["PostgreSQL", "MySQL", "SQLite"],
"allow_multiple": false
}
Example: Confirmation
{
"title": "Deploy",
"message": "Deploy v2.1.0 to production?",
"confirm_label": "Deploy",
"cancel_label": "Abort"
}
File Attachments
The get_multiline_input dialog supports file attachments through three methods:
| Method | How |
|---|---|
| Drag and drop | Drag files onto the textarea β a drop overlay appears |
| Paste | Cmd+V / Ctrl+V with an image or file in the clipboard |
| Upload button | Click the paperclip "Attach" button below the textarea |
Attachment behavior
- Any file type is accepted
- 5 MB per-file limit β oversized files are rejected with an inline error
- Files are base64-encoded and returned in the tool result alongside the text value
- Image previews are shown as thumbnails in the attachment chips
- Each chip shows the file name, size, and a remove button
- When no files are attached, the result is identical to the previous format (fully backward-compatible)
Result format
When attachments are present, the get_multiline_input tool returns:
{
"action": "submit",
"value": "Here is the screenshot",
"attachments": [
{
"name": "screenshot.png",
"type": "image/png",
"size": 48210,
"data": "iVBORw0KGgo..."
}
]
}
When no attachments are provided, the attachments field is omitted entirely.
Configuration
Environment variables
| Variable | Default | Description |
|---|---|---|
HITL_HOST | 127.0.0.1 | HTTP server bind address |
HITL_PORT | (ephemeral) | Fixed HTTP port. If unset, the OS assigns a random port |
HITL_NO_LAUNCH | (unset) | Set to 1 to print dialog URLs to stderr instead of auto-opening the browser |
Programmatic usage
import { BrowserDialogServer } from "human-loop-mcp/browser/browser-dialog-server";
const server = new BrowserDialogServer({
port: 8080,
launchUrl: async (url) => {
console.log(`Open: ${url}`);
},
});
Architecture
ββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client (AI Agent) β
β Claude / Cursor / Copilot CLI β
ββββββββββββββββ¬ββββββββββββββββββββββββββββ
β stdio (JSON-RPC)
ββββββββββββββββΌββββββββββββββββββββββββββββ
β index.ts Tool registration β
β service.ts Business logic β
β browser-dialog-server.ts HTTP + APIs β
β dialog-session-manager.ts Sessions β
β html.ts HTML/CSS/JS renderer β
ββββββββββββββββ¬ββββββββββββββββββββββββββββ
β HTTP (localhost)
ββββββββββββββββΌββββββββββββββββββββββββββββ
β Browser Dialog UI β
β Forms Β· Autocomplete Β· Attachments β
β Dark/light Β· Keyboard shortcuts β
ββββββββββββββββββββββββββββββββββββββββββββ
Data flow
- MCP client calls a tool (e.g.
get_multiline_input) via stdio JSON-RPC index.tsroutes the call toHumanLoopServiceservice.tstransforms args and callsBrowserDialogServer.openDialog()browser-dialog-server.tscreates a session, starts HTTP if needed, opens the browserhtml.tsrenders a self-contained HTML page with the dialog form- User submits (with optional file attachments) β the POST handler validates and resolves the session promise
- Response flows back through MCP to the AI agent, including any base64-encoded attachments
Development
npm install # Install dependencies
npm run dev # Run from source (tsx, hot-reload)
npm run build # Compile to dist/
npm test # Run tests (Vitest)
npm run typecheck # Type-check without emitting
Project structure
src/
βββ index.ts MCP server entry point & tool registration
βββ service.ts Tool handler business logic
βββ browser/
βββ browser-dialog-server.ts HTTP server, browser launcher, API endpoints
βββ dialog-session-manager.ts Session lifecycle, validation & attachment types
βββ html.ts Dialog page renderer (forms, autocomplete, attachments)
tests/
βββ service.test.ts
βββ dialog-session-manager.test.ts
βββ browser-dialog-server.test.ts
Contributing
See CONTRIBUTING.md for development setup, code style, and PR guidelines.
