hitl-proxy
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hitl-proxy Update the README to add the new configuration options."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hitl-proxy
Human-in-the-Loop MCP Server for LLM Agents
A Model Context Protocol (MCP) server that enforces human approval before any LLM agent can edit files, create files, or execute shell commands.
Works with any MCP-compatible IDE: opencode, Cursor, Windsurf, VS Code Copilot, and others.
The Problem It Solves
LLMs are trained to be helpful and complete tasks — which means they tend to assume, infer, and act without checking with the human first. In a coding assistant context, this leads to:
Unreviewed file edits
Destructive commands run without warning
Assumed context that was never verified
hitl-proxy inserts a mandatory human checkpoint before every write operation.
Related MCP server: Agent File Guardian
How It Works
LLM wants to edit a file
│
▼
edit_hitl({ ..., approved: false }) ← First call
│
▼
HITL Proxy blocks + issues sessionToken
Returns: "Use question() to ask the user. Token: abc-123"
│
▼
LLM uses question() → human sees options → human approves
│
▼
edit_hitl({ ..., approved: true, sessionToken: "abc-123" }) ← Second call
│
▼
HITL Proxy validates token → executes edit → logs to audit fileEnforcement Mechanisms
Mechanism | Description |
Session Tokens |
|
Violation Counter | Counts how many times the LLM tried to bypass HITL. Escalates warning messages at 2+ violations |
declare_intent_hitl | Optional tool for the LLM to declare intent before asking the user. Best practice flow |
Self-check Block | Every blocked response includes a mandatory self-evaluation prompt for the LLM |
Audit Log | NDJSON log of every action (approved or blocked) with timestamp and metadata |
Path Traversal Protection | File paths are validated against |
Cross-platform Bash | Uses |
Installation
# In your project directory
mkdir hitl-proxy
cd hitl-proxy
# Copy src/index.js and package.json from this repo
npm installConfiguration
opencode.json
{
"mcp": {
"hitl-proxy": {
"type": "local",
"command": ["node", "./hitl-proxy/src/index.js"],
"enabled": true
}
},
"permission": {
"edit": "deny",
"write": "deny"
}
}Critical: The
"edit": "deny"and"write": "deny"permissions are mandatory. Without them, the LLM will use the native IDE tools and bypass the proxy entirely.
See config/opencode.example.json for a full example.
Environment Variables
Variable | Default | Description |
|
| Root directory. File paths are validated against this |
|
| Path to the NDJSON audit log file |
|
| Session token TTL in milliseconds |
|
| Shell command timeout in milliseconds |
|
| Name of the IDE's human-input tool |
Set them in your MCP server command:
"command": ["node", "./hitl-proxy/src/index.js"],
"env": {
"HITL_PROJECT_ROOT": "/path/to/your/project",
"HITL_TOKEN_TTL": "600000"
}Tools Reference
declare_intent_hitl (best practice — call before question())
Declares what the LLM intends to do and why. Returns a sessionToken.
Parameters:
action — "edit" | "write" | "bash"
target — file path or command
reason — why this action is needed nowedit_hitl
Edits an existing file by replacing a text fragment.
Parameters:
filePath — file to edit
oldString — exact text to replace
newString — replacement text
replaceAll — (optional) replace all occurrences, not just first
approved — true only if user approved via question()
sessionToken — token from block response or declare_intent_hitlwrite_hitl
Creates or overwrites a file.
Parameters:
filePath — file to create
content — full file content
approved — true only if user approved via question()
sessionToken — token from block response or declare_intent_hitlbash_hitl
Executes a shell command.
Parameters:
command — shell command to run
approved — true only if user approved via question()
sessionToken — token from block response or declare_intent_hitlIdeal LLM Workflow (Best Practice)
1. declare_intent_hitl({ action: "edit", target: "src/app.js", reason: "Fix typo in error message" })
→ receives sessionToken: "uuid-xxx"
2. question("¿Apruebas editar src/app.js para corregir el mensaje de error?", options: ["✅ Sí", "❌ No"])
→ user selects "✅ Sí"
3. edit_hitl({ filePath: "src/app.js", oldString: "...", newString: "...", approved: true, sessionToken: "uuid-xxx" })
→ ✅ Editado: src/app.jsAudit Log Format
Each line is a JSON object:
{"ts":"2026-08-29T21:30:00.000Z","action":"edit","target":"src/app.js","approved":true,"violations":0}
{"ts":"2026-08-29T21:31:00.000Z","action":"bash","target":"rm -rf /","approved":false,"violations":1}Compatibility
IDE/Tool | Compatible | Notes |
opencode | ✅ Native |
|
Cursor | ⚠️ Partial | MCP supported; |
Windsurf | ✅ Likely | Active MCP support |
VS Code Copilot | ⚠️ Partial | Growing MCP support |
Custom agents | ✅ Adaptable | Replace |
If your IDE doesn't have
question(), the LLM can still ask in plain text — but there's no UI enforcement. SetHITL_QUESTION_TOOLto match your IDE's tool name.
System Prompt Integration
For maximum HITL enforcement, load docs/hitl_protocol.md as the last system instruction in your IDE config.
Tokens at the end of the context receive more attention from transformers (recency bias). Loading HITL rules last maximizes compliance.
See docs/llm_enforcement.md for the full guide on writing effective HITL system prompts.
License
MIT
Available Tools
4 toolsbash_hitlA
Ejecuta un comando shell. REQUIERE aprobación humana. ⚠️ Comandos destructivos (rm, del, drop, truncate, reset) son especialmente sensibles.
Flujo correcto (dos llamadas):
Llama con approved: false → recibirás instrucciones y un sessionToken
Usa question() mostrando el comando exacto y su riesgo potencial
Llama de nuevo con approved: true + el sessionToken recibido
Inputs: command (required), approved (required), sessionToken.
declare_intent_hitlA
[MEJOR PRÁCTICA — úsalo antes de question()] Declara explícitamente qué vas a hacer y por qué, ANTES de pedir aprobación al usuario. Devuelve un sessionToken para usar en la acción final.
Flujo ideal:
declare_intent_hitl({ action, target, reason }) → obtén sessionToken
question() → pide aprobación al usuario
edit_hitl / write_hitl / bash_hitl con approved: true + sessionToken
Inputs: action (required), reason (required), target (required).
edit_hitlA
Edita un archivo existente reemplazando un fragmento de texto. REQUIERE aprobación humana.
Flujo correcto (dos llamadas):
Llama con approved: false → recibirás instrucciones y un sessionToken
Usa question() para mostrar el cambio al usuario y pedir aprobación
Llama de nuevo con approved: true + el sessionToken recibido
Inputs: approved (required), filePath (required), newString (required), oldString (required), +2 more.
write_hitlA
Crea o sobreescribe un archivo completo. REQUIERE aprobación humana.
Flujo correcto (dos llamadas):
Llama con approved: false → recibirás instrucciones y un sessionToken
Usa question() para mostrar el archivo al usuario y pedir aprobación
Llama de nuevo con approved: true + el sessionToken recibido
Inputs: content (required), approved (required), filePath (required), sessionToken.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct action (declare intent, edit, write, bash), but edit_hitl and write_hitl both handle file changes and the relationship between declare_intent_hitl's sessionToken and the per-action sessionToken is not fully clear. Overall, agents should be able to select the right tool with the guidance provided.
All tools share the _hitl suffix and follow a verb prefix pattern. declare_intent_hitl uses a compound verb while the others use single verbs, creating a slight inconsistency, but the pattern remains predictable and readable.
Four tools is well-scoped for a proxy server that adds human-in-the-loop approval to common operations. Each tool has a clear role and no redundant entries inflate the surface.
The server covers the core file edit/write and shell execution actions needed for an approval proxy, plus an explicit intent declaration step. Missing session audit/cancel tools are minor gaps that don't block the primary workflow.
Maintenance
Related MCP Connectors
Preventive human-approval write-gate for AI agents: writes commit only after a human approves.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Authorize AI agent tool calls before they run: policy-as-code, human approval, signed receipts.
Runtime permission, approval, and audit layer for AI agent tool execution.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables secure, audited file operations with LLMs by enforcing implementation plans, restricting writes to approved file scopes, and maintaining a tamper-evident audit log with stub detection.547 npm-
- AlicenseNot gradedqualityDmaintenanceProvides a human-in-the-loop security layer for AI agents by intercepting file operations, explaining them with a local LLM, and enforcing a deterministic policy that requires user approval for risky actions.MIT
- AlicenseNot gradedqualityCmaintenanceGates agent tool execution with human approval, audit trails, and replay-resistant permits, enabling safe use of tools in agent loops.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI coding agents to evaluate actions against team-defined policies, record decisions, and obtain human approvals for potentially risky operations.63 npm1-