KontrolBLOCK
MCP development workspace and ACP bridge for controlled, observable collaboration between web AI interfaces and CLI coding agents.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Kontrol
A local control plane for WebUI and CLI coding agents: MCP workspace access, ACP worker dispatch, human review gates, and policy authority.
[](https://raw.githubusercontent.com/B-A-M-N/Kontrol/main/docs/assets/kontrol-control-plane.png)
Your machine. Your agents. Your approval gate.
Kontrol is a self-hosted control plane for extending WebUI and CLI coding agents in a specific, review-gated way. It exposes your local project files over MCP, dispatches bounded work to registered ACP agents, routes results back through human review, and enforces policy around the tools and paths agents can touch.
You run it on your machine, expose it through a tunnel you control, and decide which agents get to operate, what they can do, and when their work is allowed to land.
What Makes It Different
Most MCP file-server bridges stop at "read/write/edit." Kontrol adds three layers on top:
Ralphie Muntz Loop — Agents submit work for human review. The WebUI reviewer (or another authorized MCP reviewer) shows the backend-neutral checkpoint diff. Human approves, requests changes, or rejects. The agent continues from durable feedback state — even if the agent process died and restarted.
Continuation Outbox — Every review decision generates a structured continuation packet with verdict, required actions, and resumption instructions. The packet crosses from the review surface to the next agent turn, so work continues without losing context.
Policy Mode — Per-tool and per-path approval rules. A dangerous command can require a one-time approval, or you can approve it for an entire workspace session. Read-o
8111fff894a0OBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add kontrol --env KONTROL_ACP_ADAPTER_SECRET=${KONTROL_ACP_ADAPTER_SECRET} --env KONTROL_ACP_AGENT_SECRET=${KONTROL_ACP_AGENT_SECRET} --env KONTROL_ACP_REVIEWER_SECRET=${KONTROL_ACP_REVIEWER_SECRET} --env KONTROL_ACP_WORKER_SECRET=${KONTROL_ACP_WORKER_SECRET} -- npx -y @b-a-m-n/[email protected]{
"mcpServers": {
"kontrol": {
"command": "npx",
"args": [
"-y",
"@b-a-m-n/[email protected]"
],
"env": {
"KONTROL_ACP_ADAPTER_SECRET": "${KONTROL_ACP_ADAPTER_SECRET}",
"KONTROL_ACP_AGENT_SECRET": "${KONTROL_ACP_AGENT_SECRET}",
"KONTROL_ACP_REVIEWER_SECRET": "${KONTROL_ACP_REVIEWER_SECRET}",
"KONTROL_ACP_WORKER_SECRET": "${KONTROL_ACP_WORKER_SECRET}"
}
}
}
}Exposed tools (11)
6 read · 4 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
kontrol-agent-registry | read | Register, discover, and list peer agents. For agent-to-agent routing. |
kontrol-approval-remediation | read | Remediate the Kontrol approval/audit findings (P0.1-P0.5, cross-conversation ownership, P1s): DeepSeek implements, Qwen reviews, MiniMax signs off only remediated items. |
kontrol-edit | write | Edit a file by replacing exact text blocks. |
kontrol-glob | read | Find files by glob pattern. |
kontrol-grep | read | Search file contents by pattern. |
kontrol-read | read | Read a file from the workspace. |
kontrol-review | write | Submit work for human review and await feedback. |
kontrol-shell | write | Execute a shell command in the workspace. |
kontrol-submit-work-to-webui | write | Submit completed work (diff/checkpoint) to the Kontrol WebUI for human review. (Ralphie Muntz Loop terminus: the WebUI |
kontrol-write | destructive | Write or overwrite a file in the workspace. |
mwf | read | Multi-model coding workflow with auto-escalation. Routes through haiku-reviewer, opus-architect, main-implementer, sonnet-reviewer, and fable-critical-gate based on task complexity. |
Trust audit
BLOCKgrade D · trust 60/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | FAIL |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (6 observation(s))
- Network
- declared (12 observation(s))
- Shell
- declared (6 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- found
Findings (20)
heavy-payload.tsx
payload-mount.ts
raw-payload.tsx
review-payload.tsx
const sqlite = (database as { sqlite: { exec(q: string): unknown } }).sqlite;# KONTROL_ACP_AGENTS=cli-coding-agent=http://127.0.0.1:9877,hermes-agent=http://127.0.0.1:9911
# KONTROL_ACP_URL=http://127.0.0.1:7676/acp
# KONTROL_BRIDGE_URL=http://127.0.0.1:7676/mcp
const token = "test-bearer-that-is-long-enough";
kontrol-write
console.log(`\nworker-token: ${pass} passed\n`);import { AgentRegistrationError } from "../../acp-registry.js";import { isLoopbackAgentUrl } from "../../acp-gateway.js";import { constantTimeStringEqual } from "../../mcp/workspace-server.js";import type { WorkspaceRegistry } from "../../workspaces.js";import type { WorkSessionManager } from "../../work-sessions.js";headers: { Location: "https://evil.example.test/exfil" },KONTROL_PUBLIC_BASE_URL: http://127.0.0.1:7676
npm run soak:beta -- --hours 12 --build-id CANDIDATE_BUILD_ID --diagnostics-secret "$KONTROL_DIAGNOSTICS_SECRET" --tunnel-url http://127.0.0.1:8080
@clack/prompts, @earendil-works/pi-coding-agent, @pierre/diffs, better-sqlite3, diff, drizzle-orm, express, react
Gates applied: no_behavioural_pass.
8111fff894a0full audit observations/trust-audit/mcp-server/b-a-m-n__kontrol.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | 8111fff894a0 | BLOCK | D | 60 | first audit |
Questions
What is the Kontrol MCP server?
MCP development workspace and ACP bridge for controlled, observable collaboration between web AI interfaces and CLI coding agents.
What tools does Kontrol expose?
11 in total: 6 read-only, 4 that write, and 1 that can delete or overwrite (kontrol-write). Every one is listed on this page with its risk.
Is Kontrol safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (60/100) and found 5 critical or high issues in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Kontrol need?
It reads KONTROL_ACP_ADAPTER_SECRET, KONTROL_ACP_AGENT_SECRET, KONTROL_ACP_REVIEWER_SECRET, KONTROL_ACP_WORKER_SECRET, KONTROL_AUTH_MODE, KONTROL_DEPLOYMENT_LOCK_TOKEN, KONTROL_DIAGNOSTICS_SECRET, KONTROL_MCP_CANARY_AUTHORIZATION, KONTROL_MCP_CANARY_AUTH_FILE, KONTROL_OAUTH_OWNER_TOKEN, KONTROL_RUNTIME_LOCK_TOKEN and KONTROL_TUNNEL_REVIEWER_SECRET from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Kontrol run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as @b-a-m-n/kontrol at 1.0.4.
How current is this page?
The grade is for one exact copy of the source (8111fff894a0), read on 2026-10-11. The repository is watched and re-audited when it changes.