Which integrations are available for this server?

Routes human approval requests through Slack webhooks for notification and approval of AI assumptions. Routes human approval requests through Telegram, allowing interactive approval, rejection, and answering of AI assumptions via bot commands.

How do I use Kontrol Freek?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Kontrol Freek check assumption: use AWS Lambda for deployment" 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.

Kontrol Freek

by berkbayri

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Kontrol Freek — AI Assumption Firewall for MCP Agents

Kontrol Freek is an open-source Model Context Protocol (MCP) server that acts as an AI safety guardrail for autonomous agents. It intercepts AI assumptions before they cause irreversible mistakes, verifies every decision against a persistent project log, detects contradictions, scores risk, and routes human approval requests through Telegram, Slack, or native MCP elicitation — all without blocking your workflow.

Gate every AI assumption. Keep humans in the loop. Prevent agentic mistakes before they happen.

Why Kontrol Freek?

AI agents and coding assistants make implicit assumptions constantly — about architecture choices, file locations, API designs, and deployment targets. Without a structured checkpoint, these assumptions silently accumulate into hard-to-reverse technical debt or outright mistakes.

Kontrol Freek solves the human-in-the-loop problem for MCP agents: it sits between your AI agent and every risky decision, comparing new assumptions against your project's history, flagging contradictions, and routing approval requests to you — wherever you are.

Kontrol Freek adds a decision firewall between your AI agent and every risky action:

AI: "I'll use PostgreSQL for this project"   ← assumption
         ↓
check_assumption("Use PostgreSQL", risk="medium", category="architecture")
         ↓
Kontrol Freek: query past decisions → detect contradictions → score risk
         ↓
├─ Low risk + past approval match  → ✅ Auto-approve, continue
├─ Medium risk / new decision      → 🔍 Notify human (Telegram / Slack / elicit)
└─ Contradiction or critical risk  → ⛔ Block + require explicit approval

Related MCP server: @vaibot/mcp-server

Key Features

Feature	Description
Assumption interception	Catches AI guesses before they execute
SQLite decision log	Persists every decision per project
Semantic similarity	Finds related past decisions using TF-IDF or sentence-transformers
Contradiction detection	Blocks decisions that conflict with approved history
Risk scoring	Adaptive policy engine — auto-approve low risk, gate high risk
Time-based decay	Old decisions lose weight; prevents stale approvals
Telegram polling	Background loop processes `/kf approve/reject/answer` commands
Multi-channel routing	ctx.elicit() → Telegram → Slack → Web dashboard
HMAC-SHA256 audit trail	Cryptographically signed, hash-chained decision log
Per-project isolation	Each project gets its own DB, audit log, and config
MCP native	Works with any MCP-compatible client

How It Compares

Feature	clarify-mcp	CONTINUITY	mcp-human-loop	VantaGate	Kontrol Freek
ctx.elicit() support	✅	❌	❌	❌	✅
SQLite decision log	❌	✅	❌	❌	✅
Risk scoring	❌	❌	✅	❌	✅
Semantic similarity	❌	❌	❌	❌	✅
Contradiction detection	❌	❌	❌	❌	✅
Cryptographic audit trail	❌	❌	❌	✅	✅
Time-based decision decay	❌	❌	❌	❌	✅
Telegram interactive approval	❌	❌	❌	❌	✅
Per-project isolation	❌	❌	❌	❌	✅
Adaptive policy engine	❌	❌	Basic	Static	Adaptive

Installation

pip (recommended)

pip install kontrol-freek-mcp

One-command setup (macOS / Linux / Windows)

git clone https://github.com/berkbayri/kontrol-freek-mcp.git
cd kontrol-freek-mcp
python install.py

The installer:

Installs the Python package
Generates a .env with a random HMAC secret
Registers a system service (auto-start on boot, crash recovery)
Registers the MCP server with compatible clients automatically

Manual install

pip install -e ".[full]"   # Full: Telegram + Web + sentence-transformers embeddings
pip install -e ".[lite]"   # Lite: Telegram + Web (no embeddings)
pip install -e .           # Minimal: stdio only

Configuration

MCP client config

Add to your MCP client's server configuration (mcpServers block):

{
  "mcpServers": {
    "kontrol-freek": {
      "command": "kontrol-freek",
      "env": {
        "KF_HMAC_SECRET": "your-secret",
        "KF_TELEGRAM_TOKEN": "your-bot-token",
        "KF_TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

Or using python -m if installed without the entry point:

{
  "mcpServers": {
    "kontrol-freek": {
      "command": "python",
      "args": ["-m", "kontrol_freek_mcp"],
      "env": {
        "KF_HMAC_SECRET": "your-secret"
      }
    }
  }
}

Per-project config (`.kontrol-freek.json`)

Place this file in your project root to override global credentials and set a project name:

{
  "project_name": "my-app",
  "telegram_token": "bot-token-override",
  "telegram_chat_id": "chat-id-override",
  "slack_webhook": ""
}

Per-project config is detected automatically — no restart required when the file changes.

HTTP server mode (remote / multi-user)

kontrol-freek --transport streamable-http --port 8765

{
  "mcpServers": {
    "kontrol-freek": {
      "transport": "streamable-http",
      "url": "http://localhost:8765/mcp"
    }
  }
}

Telegram Setup

Message @BotFather → /newbot → copy the token
Start a DM with your bot or add it to a group
Get your chat ID: https://api.telegram.org/bot<TOKEN>/getUpdates
Set credentials in .env or .kontrol-freek.json

Telegram commands

/kf approve <id>              Approve a pending assumption
/kf reject <id> [reason]      Reject with an optional reason
/kf answer <id> <answer>      Answer a direct question

Kontrol Freek runs a background long-poll loop — no webhook setup needed. Commands are processed in real time while the MCP server is running.

MCP Tools Reference

Always pass project_root as your current working directory so decisions are isolated per project.

Tool	When to use
`check_assumption`	At every decision point — architecture, file paths, API choices, etc.
`confirm_decision`	To record a finalized decision; set `is_irreversible=True` for destructive actions
`ask_human`	When genuinely uncertain — prompts human via Telegram/Slack/elicitation
`query_decisions`	At the start of a task — load prior context before making new decisions
`revoke_decision`	When a past decision is no longer valid — prevents it from influencing future auto-approvals
`get_firewall_stats`	View approval rates, total decisions, and activity by category
`healthcheck`	Verify DB, audit chain, and notification channel health
`setup_project`	Initialize per-project config on first use

`check_assumption` response statuses

Status	Meaning	Agent should…
`auto_approved`	Low risk, matches prior approved decision	Proceed
`pending_review`	Human review recommended (architecture / security / deployment)	Proceed with caution — call `confirm_decision()` when task is done
`blocked`	Contradiction detected or critical risk	Stop — do not proceed without explicit human approval
`human_approved`	Human approved via Telegram/Slack	Proceed
`human_rejected`	Human rejected	Stop and reconsider

How It Works

Decision flow

AI calls check_assumption(assumption, risk_level, category, project_root)
    │
    ├── Query SQLite for similar past decisions
    ├── Compute semantic similarity score (TF-IDF or sentence-transformers)
    ├── Run contradiction analysis
    ├── Policy engine → auto_approve / review / block
    │
    ├── auto_approve    → log, return status: "auto_approved"
    ├── pending_review  → log, return status: "pending_review" (non-blocking)
    │                     optionally notify Telegram/Slack in background
    └── block           → log, return status: "blocked"
                          if Telegram/Slack configured → notify + wait (3 min max)
                          │
                          ├── Telegram bot    (/kf approve/reject <id>)
                          └── Slack webhook   (text instructions)

Policy rules

Condition	Verdict
`critical` risk	⛔ Block — always requires human approval
Contradiction with approved decision	⛔ Block
Category: `security`, `architecture`, `deployment`	🔍 Human review
Low risk + ≥78% similarity + prior approval	✅ Auto-approve
`high` risk	🔍 Human review
Default	🔍 Human review

Time-based decision decay

Older decisions carry less weight in similarity matching, preventing stale approvals from auto-approving new assumptions:

Age	Weight
0 days	1.00
30 days	0.72
90 days	0.37
180 days	0.14

Cryptographic audit trail

Every action is written to an HMAC-SHA256 signed, hash-chained JSONL file:

{
  "action": "human_approve",
  "text": "Use PostgreSQL",
  "detail": "Approved via Telegram",
  "decision_id": 42,
  "ts": "2025-01-15T14:30:00Z",
  "prev": "a1b2c3...",
  "hash": "d4e5f6..."
}

Verify audit chain integrity:

from kontrol_freek_mcp.audit import AuditTrail
trail = AuditTrail("~/.kontrol-freek/projects/my-app/audit.jsonl", "your-secret")
valid, count = trail.verify_chain()
print(f"Chain valid: {valid} — {count} entries")

Auto-Start & Crash Recovery

python install.py configures an OS-native service:

Platform	Mechanism	Details
macOS	LaunchAgent	`~/Library/LaunchAgents/com.kontrol-freek.mcp.plist` — starts at login, `KeepAlive` restarts on crash
Linux	systemd user service	`~/.config/systemd/user/kontrol-freek.service` — `Restart=on-failure`, persists across logouts via `loginctl enable-linger`
Windows	Task Scheduler	`schtasks` — triggers at logon

The wrapper script includes exponential backoff (5s → 10s → 20s → ..., max 10 restarts).

python install.py --status     # Health check
python install.py --uninstall  # Clean removal

Project Structure

kontrol-freek-mcp/
├── src/kontrol_freek_mcp/
│   ├── server.py        # MCP server — 7 tools, 2 resources, 1 prompt
│   ├── db.py            # SQLite decision database
│   ├── policy.py        # Adaptive policy engine (risk scoring, decay)
│   ├── similarity.py    # Semantic similarity (TF-IDF + sentence-transformers)
│   ├── notifier.py      # Multi-channel routing + Telegram polling loop
│   ├── audit.py         # HMAC-SHA256 hash-chain audit trail
│   └── web.py           # FastAPI approval dashboard
├── tests/
├── install.py           # One-command installer
├── pyproject.toml
├── .env.example
└── README.md

License

MIT — free to use, modify, and distribute.

Available Tools

8 tools

ask_humanB

Ask the human a direct question and wait for their response. Call this whenever uncertain. Always pass project_root as the current working directory.

Inputs: question (required), context, options, urgency, +1 more. Returns: object

check_assumptionA

Verify an assumption against past decisions. Checks for contradictions, scores risk, and requests human approval when needed.

ALWAYS pass project_root as the current working directory so decisions are stored per-project and not mixed across projects.

The AI MUST call this at every decision point:

When guessing instead of using confirmed info
When choosing between multiple valid options
When the choice might contradict a previous decision
Before any hard-to-reverse step

Inputs: assumption (required), context, category, risk_level, +2 more. Returns: object

confirm_decisionA

Record a finalized decision. Irreversible decisions always require human approval. Always pass project_root as the current working directory.

Inputs: decision (required), rationale (required), category, project_root, +2 more. Returns: object

get_firewall_statsA

Return firewall statistics for the current project. Always pass project_root as the current working directory.

Inputs: project_root. Returns: object

healthcheckA

Full health check — DB, audit chain, channels. Always pass project_root as the current working directory.

Inputs: project_root. Returns: object

query_decisionsA

Search past decisions for context and consistency. Always pass project_root as the current working directory.

Inputs: limit, status, keyword, category, +1 more. Returns: object

revoke_decisionA

Revoke or supersede a previously approved decision.

Use this when a past decision was wrong, circumstances changed, or it conflicts with new requirements. The decision is marked 'revoked' in the log so future similarity checks ignore it.

Always pass project_root as the current working directory.

Inputs: reason (required), decision_id (required), project_root. Returns: object

setup_projectA

Initialize Kontrol Freek for the current project.

Checks if .kontrol-freek.json exists in the project root. If not, analyzes project files to infer a configuration, then asks the human for confirmation before writing the file.

Always pass project_root as the current working directory. Call this at the start of every session in a new project.

Inputs: project_root. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-08-30 14:30 across 8 tools

Disambiguation4/5

Decision-related tools are mostly distinct: check_assumption verifies, confirm_decision records, query_decisions searches, revoke_decision invalidates. Some overlap exists between check_assumption and ask_human since both can involve seeking human input, but their primary purposes remain distinguishable.

Naming Consistency4/5

Most tool names follow a clear verb_noun snake_case pattern: check_assumption, confirm_decision, query_decisions, revoke_decision, get_firewall_stats, setup_project. The single deviation is 'healthcheck', which is a compound noun without an explicit verb separator, but it is still readable and consistent in style.

Tool Count5/5

Eight tools is a well-scoped set for a decision-management server. Each tool has a clear role in the lifecycle, and the count is within the ideal range without redundancy or bloat.

Completeness4/5

The decision lifecycle is well covered: setup, assumption checking, confirmation, querying, revocation, and human escalation are all present. Minor gaps exist, such as no explicit update_decision operation, but revoke_decision handles superseding, and healthcheck/stat tools round out operational coverage.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
https://api.microservices.sh/mcp
Flowra
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
IdentArk Gateway
io.identark
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Security Agent Orchestration
29
https://api.identark.io/v1/mcp/rpc
Server4AgentA
com.server4agent
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
App Automation Cloud Platforms Developer Tools
343
https://mcp.server4agent.com

Related MCP Servers

call-a-human-mcp
Autonomous Agents Communication
nishantmodak
A
license
A
quality
A
maintenance
An MCP server that enables AI agents to pause and request human approval or information via Slack, Telegram, or macOS dialogs before proceeding with actions.
Updated 2 months ago (2026-09-13 03:54 UTC)
2
15
Apache 2.0
@vaibot/mcp-serverofficial
Security Autonomous Agents
vaibot-io
A
license
A
quality
D
maintenance
Governance circuit-breaker MCP server that enables AI agents to request risk-based decisions, approve or deny actions, and finalize outcomes with full audit receipts.
Updated 8 months ago (2026-03-18 21:34 UTC)
4
MIT
AgentOps Guardian MCP
Developer Tools Security
RZFL
A
license
Not graded
quality
D
maintenance
An MCP server that provides on-demand safety for AI coding workflows, enabling inspection, review, checkpointing, and rollback of risky actions.
Updated 4 months ago (2026-07-06 14:15 UTC)
72 npm
1
MIT
approval-gate
Security Autonomous Agents
yulinlina
A
license
Not graded
quality
C
maintenance
MCP server that provides human-in-the-loop approval for risky AI agent actions, with durable state and audit logs.
Updated 3 months ago (2026-08-07 07:31 UTC)
MIT

Kontrol Freek — AI Assumption Firewall for MCP Agents

Why Kontrol Freek?

Key Features

How It Compares

Installation

pip (recommended)

One-command setup (macOS / Linux / Windows)

Manual install

Configuration

MCP client config

Per-project config (.kontrol-freek.json)

HTTP server mode (remote / multi-user)

Telegram Setup

Telegram commands

MCP Tools Reference

check_assumption response statuses

How It Works

Decision flow

Policy rules

Time-based decision decay

Cryptographic audit trail

Auto-Start & Crash Recovery

Project Structure

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

call-a-human-mcp

@vaibot/mcp-serverofficial

AgentOps Guardian MCP

approval-gate

Per-project config (`.kontrol-freek.json`)

`check_assumption` response statuses