hitl-mcp
MCP server where an agent asks a human questions and waits for answers, which arrive through MCP tools or an HTTP API.
- 128 ★ on the repository
- Last commit
Extended access
Why this level
- On timeout the server answers questions with defaults, so a confirmation can pass without a human.
- The HTTP API listens on all interfaces on port 3000 by default.
Install
- Works in
Manual install
git clone https://github.com/ZenlixAI/hitl-mcp.git && cd hitl-mcp && npm install && npm run devThe README shows a `<your-repo-url>` placeholder; the repository address is filled in here. Alternative: a Docker image built from the `Dockerfile`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- On timeout the server answers questions with defaults, so a confirmation can pass without a human.
- The HTTP API listens on all interfaces on port 3000 by default.
This is third-party code. Review the repository files before installing.
What it does
hitl-mcp stores an agent's questions for a human and returns the answers. The agent creates questions with the `hitl_ask` tool and immediately calls `hitl_wait`. The human answers in their own interface: one option from a list, several options, text, yes or no, a number in a range. Partial answers, skipping optional questions and cancelling are supported. Every question is tied to a caller scope: agent identity and session ID taken from headers. Two agents never collide, even with identical questions. Waiting applies to the whole scope, not one question, and in `progressive` mode it fires after each answer. The same state is reachable through an HTTP API under `/api/v1`, so an operator console or backend can show questions and submit answers. Storage defaults to memory; Redis is used for multiple processes.
Who it is for. Developers of agent systems that need a pause for human confirmation with a separate interface for the operator.
Good fit when
- An agent must get a yes or no from the on-call person before a release.
- Several agents need clarifications and answers must never mix between sessions.
- An operator answers agent questions in their own web panel rather than a console.
- Confirmation arrives in parts and the agent reacts to each one.
Not a fit when
- You need a ready interface with buttons: the project ships no console.
- You need a task queue or business process orchestrator: the server stores questions only.
- A confirmation must never be replaced by a default value.
Example request
Before deleting branches, ask me through hitl_ask whether I confirm, and wait for the answer through hitl_wait.MCP
- Transport
- http
- Authentication
- not required
Environment variables
MCP_URL- Public server address for MCP metadata, default `http://0.0.0.0:3000`.
HITL_STORAGE- Storage backend: `memory` by default or `redis`.
HITL_REDIS_URL- Redis URL when `redis` storage is selected.
Limitations
There is no ready interface for the human: your backend or console fetches questions through the HTTP API. Installation is from source or a Docker image. When the timeout expires, 900 seconds by default, the server answers remaining questions itself with defaults such as `true` for a boolean question, so set `default_answer` explicitly for critical confirmations. Memory storage does not survive a restart; durable storage needs Redis. The server version in default settings is 0.1.0.
How to disable. Remove the `hitl-mcp` entry from the MCP client configuration and stop the server or container. If you used Redis, clear keys with the `hitl` prefix separately.
FAQ
How do I run hitl-mcp locally?
Clone the repository and run `npm install` and `npm run dev`. The server listens on port 3000: MCP at `/mcp`, HTTP API at `/api/v1`.
Which question types exist?
Five types: `single_choice`, `multi_choice`, `text`, `boolean` and `range`. A `single_choice` option can carry follow-up fields, and required ones are validated.
What happens if the human does not answer?
After the timeout the server answers with defaults and marks such answers as automatic. A boolean question defaults to `true`.
How do I enable Redis?
Set `HITL_STORAGE=redis` and `HITL_REDIS_URL`. Timeouts and waiting then work across several server instances.
How do I keep different agents' questions apart?
Send the `x-agent-identity` and `x-agent-session-id` headers: together they define the caller scope, and questions from different scopes never mix.
Discussion
No questions or reviews yet.
Related
MCP serversA Node.js MCP server through which an agent controls Home Assistant devices and edits its automations
Open Agent Email — a self-hosted mail server for AI agents: inboxes, in-thread replies, human approval, webhooks and an MCP endpoint with 96 tools
Hycli turns a website URL and a goal into a typed CLI and MCP tools that run in your own browser session, with no cookie leaks.
The Apideck MCP server: an agent works with over 200 business systems: accounting, HRIS, CRM and files through one unified API
An MCP server for Home Assistant: the agent reads smart-home state and controls devices through your instance
An MCP server for driving Windows: the agent opens apps, clicks and types, reads window and UI state, and works with files and PowerShell
README in short
The README explains the question model, caller scope and wait modes, then lists the MCP tools, HTTP API routes and environment variables. Separate sections cover architecture, metrics and operations.