by goweft
Provides a policy‑and‑trust layer for MCP tool servers, turning declarative YAML configurations into validated, policy‑enforced MCP tools with built‑in credential brokering and tamper‑evident audit logging.
Heddle adds a security and governance envelope around MCP tool servers. By writing a single YAML file you define an entire tool agent – its metadata, exposed functions, HTTP bridging, and required trust tier. Heddle validates the config, signs it, and runs it as a fully‑featured MCP server that enforces runtime policies, resolves secrets, and records every call in a hash‑chained audit log.
git clone https://github.com/goweft/heddle.git
cd heddle
python -m venv venv
source venv/bin/activate
pip install -e "[dev]"
heddle validate agents/prometheus-bridge.yaml
heddle run agents/prometheus-bridge.yaml --port 8200
heddle mesh agents/
heddle generate "agent that wraps the weather API at localhost:5000"
heddle audit show -n 20
heddle audit verify
{{secret:key}} placeholders are resolved at runtime, never stored in the config.Q: Do I need to write Python code for each tool? A: No. All functionality is described in YAML; Heddle generates the MCP server automatically.
Q: How are secrets protected? A: Secrets are stored outside the config and injected at runtime through the credential broker; they never appear in the YAML file.
Q: What happens if an audit log entry is tampered with?
A: The hash chain breaks; heddle audit verify will detect the break and you should rotate the log as described in the documentation.
Q: Can I run Heddle in production with high availability? A: Yes. The mesh launcher can be supervised (systemd, Docker, etc.) and the audit logger supports file locking to avoid chain breaks.
Q: Is sandbox isolation already enforced? A: Container configuration is generated, but full runtime network/isolation enforcement is still in the roadmap (planned).
One config, one MCP server. This YAML is a complete tool server — no Python, no boilerplate:
agent:
name: prometheus-bridge
version: "1.0.0"
description: "Bridges Prometheus for natural language metric queries"
exposes:
- name: query_prometheus
description: "Run a PromQL query"
parameters:
query: { type: string, required: true }
- name: get_alerts
description: "List active Prometheus alerts"
http_bridge:
- tool_name: query_prometheus
method: GET
url: "http://localhost:9090/api/v1/query"
query_params: { query: query }
- tool_name: get_alerts
method: GET
url: "http://localhost:9090/api/v1/alerts"
runtime:
trust_tier: 1 # enforced: GET/HEAD only, no writes, no cross-agent calls
Run it:
heddle run agents/prometheus-bridge.yaml
Claude can now query Prometheus in natural language.
Current demo environment: 46 tools from 9 active configs through a single MCP connection (11 configs total, 2 excluded for incompatible transports).
daily-ops (T3): daily_briefing, system_health_check, threat_landscape
gitea-api-bridge (T1): list_user_repos, list_repo_issues
grafana-bridge (T1): list_dashboards, get_dashboard, list_datasources, get_alert_rules, grafana_health
ai-platform (T1): health, ai_status, routing_stats, routing_costs, list_apps, detect_drift, ...
ollama-bridge (T2): list_models, list_running, generate, show_model
prometheus-bridge(T1): query_prometheus, query_range, get_targets, get_alerts, get_metric_names
rsshub-bridge (T1): get_hacker_news, get_github_trending, search_arxiv, get_reuters_news
vram-orchestrator(T3): vram_status, smart_load, smart_generate, optimize_vram, unload_model, model_library
intel-rag-bridge (T2): ask_intel, get_dossier, get_trending, get_patterns, get_communities, get_stats, ...
Security is always on. Every tool call passes through trust enforcement, credential brokering, and audit logging.
Example: a T1 (read-only) agent attempted a POST and was blocked:
{
"event": "trust_violation",
"agent": "reader",
"trust_tier": 1,
"action": "http_POST",
"detail": "T1 agent cannot use POST. Allowed: ['GET', 'HEAD', 'OPTIONS']",
"severity": "high",
"chain_hash": "92c189e3..."
}
The request was rejected, the violation was logged, and the hash chain links this entry to every event before and after it.
| Heddle | Hand-written FastMCP | OpenAPI wrapper gen | n8n / workflow tools | |
|---|---|---|---|---|
| New tool | Write YAML, done | Write Python handler per tool | Generate stubs, then customize | Drag nodes, wire connections |
| Security | Trust tiers, credential broker, audit log, input validation, config signing — all built in | You build it yourself | None | Platform-level auth only |
| AI-generatable | heddle generate "wrap the Gitea API" → valid config in 20s |
LLM can write code but can't validate it | Not designed for LLM generation | Visual-only, not scriptable |
| Credentials | {{secret:key}} resolved at runtime, never in config |
Hardcoded or env vars | Hardcoded or env vars | Platform credential store |
| Audit trail | Hash-chained, tamper-evident, every call logged | You build it yourself | None | Platform logs only |
| Composability | Configs become MCP tools, mesh them together | Manual wiring | Separate services | Workflow-scoped |
Heddle is for exposing APIs as MCP tools with real runtime controls — not just connectivity. If you only need one tool with no policy layer, hand-written FastMCP is simpler. If you need a visual workflow builder, use n8n. Heddle sits between those worlds: declarative like a workflow tool, programmable like a framework, secure by default.
What Heddle can do today, what is partially implemented, and what is still planned:
| Layer | Status | Detail |
|---|---|---|
| Config → MCP server | Shipped | YAML configs become typed MCP tools with HTTP bridging |
| Trust tiers (T1–T4) | Shipped | Runtime-enforced, violations blocked and logged |
| Credential broker | Shipped | Per-config secret policy, {{secret:key}} resolution |
| Audit logging | Shipped | Hash-chained JSON Lines, tamper-evident |
| Input validation | Shipped | Type checking, injection detection, rate limiting |
| Access mode annotations | Shipped | read/write on tools, T1 write blocked at load + runtime |
| Escalation rules | Shipped | Conditional hold-for-review on parameter thresholds |
| Config signing | Shipped | HMAC-SHA256, tamper detection |
| Config quarantine | Shipped | AI-generated configs staged for review |
| AI config generator | Shipped | Natural language → validated YAML via local LLM |
| Sandbox policies | Partial | Container config generation exists; runtime isolation not yet enforced |
| Network isolation | Planned | Container-level network enforcement |
Define tools in YAML. Heddle validates the config with Pydantic, generates typed MCP tools, and bridges HTTP with {{param}} template rendering. Cross-field validation catches bad configs before they run.
Describe what you need in plain English. A local LLM generates valid YAML, Heddle validates it against schema rules, retries on failure, and saves the result.
$ heddle generate "agent that wraps the Gitea API" --model qwen3:14b
✓ Generated gitea-api-bridge.yaml (2 tools) in 20.3s
Heddle's security controls map to OWASP Agentic Top 10, NIST AI RMF, and MAESTRO. See the full threat model and security controls reference.
| Control | What It Does | Framework |
|---|---|---|
| Trust tiers | 4 levels (observer → privileged), runtime-enforced, violations blocked and logged | OWASP Agentic #3 |
| Credential broker | Per-config secret access policy, {{secret:key}} resolved at runtime, never stored in YAML |
OWASP Agentic #7 |
| Audit log | Hash-chained JSON Lines, tamper-evident, 5 event types, secret redaction | OWASP Agentic #9 |
| Input validation | Type checking, length limits, injection pattern detection (shell, SQL, LLM prompt) | OWASP Agentic #1 |
| Config signing | HMAC-SHA256 on all agent configs, tamper detection | OWASP Agentic #8 |
| Config quarantine | AI-generated configs staged for review before promotion | OWASP Agentic #8 |
| Rate limiting | Sliding window per-config per-tool | OWASP Agentic #4 |
| Sandbox policies | Docker container config generation and network policies (enforcement planned) | OWASP Agentic #6 |
| Escalation rules | Conditional hold-for-review when parameters match thresholds or patterns | OWASP Agentic #3 |
Ready-made configs for common services. Copy one into agents/, update the base URL or credentials, validate, and run. See packs/ for full docs.
| Pack | Tools | Trust | Description |
|---|---|---|---|
| prometheus | 5 | T1 read-only | PromQL queries, targets, alerts, metric discovery |
| grafana | 5 | T1 read-only | Dashboards, datasources, alert rules |
| git-forge | 3 | T1 read-only | Repos, issues (Gitea/GitHub/Forgejo) |
| ollama | 4 | T2 worker | Model listing, text generation, VRAM status |
| sonarr | 6 | T1 read-only | TV library, download queue, search, calendar, history |
| radarr | 6 | T1 read-only | Movie library, download queue, search, calendar, history |
cp packs/prometheus.yaml agents/
heddle validate agents/prometheus.yaml
heddle run agents/prometheus.yaml --port 8200
These show Heddle beyond simple API bridging.
Multiple configs share a single MCP connection to Claude Desktop. The mesh launcher loads all configs, merges tools, and serves them through one stdio transport.
A higher-trust agent that manages GPU memory across Ollama and a local GGUF model library, including smart loading and automatic eviction when VRAM is constrained.
An orchestration agent that queries Prometheus, a RAG search API, and Ollama in parallel, then synthesizes a daily operations briefing with a local model.
A FastAPI + React dashboard for mesh topology, agent status, live audit stream, credential policy, and config signatures.
git clone https://github.com/goweft/heddle.git
cd heddle
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
heddle validate agents/prometheus-bridge.yaml
heddle run agents/prometheus-bridge.yaml --port 8200
heddle generate "agent that wraps the weather API at localhost:5000"
heddle mesh agents/
heddle audit show -n 20
heddle audit verify
heddle sign all agents/
heddle sign verify agents/
heddle secrets policy
heddle sandbox agents/my-agent.yaml
Heddle's audit log at ~/.heddle/audit/audit.jsonl is a hash-chained JSONL file: every entry includes the SHA-256 of the previous entry, so a single tampered or missing line invalidates the chain from that point on. heddle audit verify walks the chain and exits non-zero on the first break.
Policy: rotate-on-break, not tolerate-and-document. A hash chain is either whole or it is broken; there is no useful middle ground. If heddle audit verify reports a break, the chain is sealed and a fresh one is started — the broken file is preserved as raw event data but is no longer the active chain. We do not carry a "known break, please ignore" exception forward, because each such exception weakens what verify is claiming and forces every consumer (CI, anomaly detection, future auditors) to special-case it.
When you'd rotate:
heddle audit verify reports a break (most commonly from concurrent writers without file locking — fixed for new entries by commit a50e203, but historical breaks pre-dating that fix remain).Manual rotation procedure (until heddle audit rotate lands; see below):
# 1. Stop the broker so no writer is active
systemctl --user stop heddle-dashboard.service # or just kill heddle-mesh / dashboard
# 2. Capture a seal record alongside the file
cd ~/.heddle/audit
SEAL_DATE=$(date -u +%Y-%m-%dT%H-%M-%SZ)
sha256sum audit.jsonl > "audit-archive-${SEAL_DATE}.sha256"
wc -l audit.jsonl >> "audit-archive-${SEAL_DATE}.sha256"
# 3. Move the broken/old chain aside
mv audit.jsonl "audit-archive-${SEAL_DATE}.jsonl"
# 4. Restart the broker; the next event creates a fresh audit.jsonl
systemctl --user start heddle-dashboard.service
# 5. Verify the new chain
heddle audit verify # should exit clean immediately
Archived chains are kept in the same directory (they're still useful as event history) but are not re-verified by heddle audit verify — that command only walks the active chain. To inspect a sealed file directly, jq -c '. | {ts, event, agent}' audit-archive-<date>.jsonl reads it as plain JSONL.
Existing 2026-03-29 break: development machines that ran the dashboard plus the test suite concurrently before the file-lock fix landed have a chain break around that date. There is no recovery path for the contiguous chain; rotating per the procedure above is the supported answer. Production-equivalent deployments (single broker writer, file locking present) should not see new breaks.
Tracked follow-up: heddle audit rotate is on the v0.2 backlog. It will (a) atomically rename the active file to a timestamped archive, (b) write a .sha256 seal alongside, and (c) seed the fresh chain with a chain_seal_predecessor event whose payload references the archive's hash so that an external auditor can chain the archives together. Until then, the manual procedure above is the documented path.
To expose a unified Heddle mesh to Claude Desktop (and optionally to CAS):
{
"mcpServers": {
"heddle-mesh": {
"command": "/path/to/heddle/venv/bin/heddle-mesh"
}
}
}
| Command | Description |
|---|---|
heddle run <config> |
Run a single agent from YAML |
heddle validate <config> |
Validate a config without running it |
heddle generate "<prompt>" |
Generate a config from natural language |
heddle mesh <dir> |
Start all agents as a unified mesh |
heddle list |
List registered agents |
heddle registry |
Show all registered tools |
heddle info <agent> |
Show detailed agent info |
heddle probe <server> |
Discover tools on a running MCP server |
heddle audit show |
Inspect audit log entries |
heddle audit verify |
Verify hash chain integrity |
heddle secrets |
Manage credential broker |
heddle sign |
Sign and verify configs |
heddle quarantine |
Stage AI-generated configs for review |
heddle sandbox <config> |
Show generated sandbox configuration |
heddle/
├── agents/ # YAML agent configs
├── packs/ # Starter pack configs
├── docs/
│ ├── threat-model.md # Threat analysis, framework-mapped
│ └── security-controls.md
├── src/heddle/
│ ├── cli.py # CLI entrypoint
│ ├── config/ # Pydantic schema and YAML loader
│ ├── mcp/ # MCP server builder, client, registry
│ ├── runtime/ # Agent runner and mesh runtime
│ ├── generator/ # AI config generator and API discovery
│ ├── security/ # Trust, credentials, audit, validation,
│ │ # signing, sandbox, escalation
│ ├── agents/ # Custom higher-level handlers
│ └── web/ # Dashboard backend and frontend
├── tests/
└── pyproject.toml # Entry points: heddle, heddle-dashboard, heddle-mesh
Python 3.11+ · FastMCP · FastAPI · Pydantic v2 · httpx · Click · SQLite · Ollama
Heddle is the trust and policy layer. The rest of the stack:
| Project | Language | What it does |
|---|---|---|
| cas | Go | Conversational Agent Shell — terminal TUI where conversation generates workspaces. Heddle adds optional trust enforcement and audit logging. |
| tenter | Python | Pre-publish artifact scanner — catches source maps, secrets, debug artifacts before they ship. On GitHub Marketplace. |
| tenter-rs | Rust | tenter v2 — static binary, no runtime required. |
| unshear | Rust | Fork divergence detector — reveals where safety mechanisms were stripped from a forked agent codebase. |
| ratine | Python | Agent memory poisoning detector. |
| crocking | Python | AI authorship detector for git repositories. |
CAS runs standalone. Heddle integration is optional and adds:
{{secret:key}} resolution, credentials never in config{
"mcpServers": {
"heddle-mesh": {
"command": "/path/to/heddle/venv/bin/heddle-mesh"
}
}
}
MIT — see LICENSE.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by chaitin
A self‑hosted web application firewall and reverse proxy that protects web applications from attacks and exploits by filtering, monitoring, and blocking malicious HTTP/S traffic.
by safedep
Provides enterprise‑grade open source software supply chain security by scanning source code, dependencies, containers and SBOMs, detecting vulnerabilities and malicious packages, and enforcing policy as code.
by semgrep
Offers an MCP server that lets LLMs, agents, and IDEs run Semgrep scans to detect security vulnerabilities in source code.
by PortSwigger
Enables Burp Suite to communicate with AI clients via the Model Context Protocol, providing an MCP server and bundled stdio proxy.
by gensecaihq
Provides AI‑driven conversational access to Wazuh SIEM data, allowing natural‑language queries, threat analysis, incident triage, and compliance checks through a Model Context Protocol‑compliant remote server.
by cycodehq
Boost security in the development lifecycle via SAST, SCA, secrets, and IaC scanning.
by mobb-dev
Provides automatic security vulnerability remediation for code via a command‑line interface and an MCP server, leveraging findings from popular SAST tools such as Checkmarx, CodeQL, Fortify, and Snyk.
by ChristophEnglisch
Provides AI‑powered administration of Keycloak users and realms through the Model Context Protocol, enabling automated creation, deletion, and listing of users and realms from MCP clients such as Claude Desktop.
by CheckPointSW
A collection of Model Context Protocol servers for Check Point security platforms, exposing structured security data through TypeScript packages.