HiveGuard MCP Wrapper
HWyn2020/hiveguard-mcp-wrapper
Gateway de segurança MCP com invariantes HiveGuard para qualquer agente
Ver no GitHubServidor MCP que expõe agentes HiveGuard ou qualquer agente como serviço seguro com primitivas de segurança endurecidas: DNS-pinned URL fetch, scrubbing de saída e redação de PII com validação de dígitos verificadores. Opera em dois modos: wrapping de agentes HiveGuard existentes ou gateway de segurança puro para qualquer framework (OpenClaw, LangChain, Mastra).
Instalação
npx convez-ai HWyn2020/hiveguard-mcp-wrapper1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Proteger operações arriscadas (fetch URL, hashing, processamento de dados sensíveis) em agentes multi-framework
- Expor agentes HiveGuard como serviços MCP com enforcement automático de políticas de segurança
- Implementar redação de PII e scrubbing de saída em tempo real para agentes TS/JS rodando OpenClaw ou LangChain.js
Veredito

Ferramenta de segurança robusta e bem testada (303 testes, 3 camadas de revisão) que resolve um problema real: trazer garantias de segurança HiveGuard para agentes em qualquer linguagem via MCP. Implementação madura e bem documentada com dois modos operacionais flexíveis.
README
A tradução para o português deste README ainda está na fila.
hiveguard-mcp-wrapper
Bring HiveGuard-grade security to any agent framework via the Model Context Protocol.
Wrap a Python HiveGuard BaseAgent as an MCP server (Mode A), or run as a pure security gateway exposing primitive tools (Mode B) that any agent — OpenClaw, LangChain, Mastra, Hermes, custom — can call for risky operations like URL fetching, hashing, or output scrubbing.
What this is
The reference MCP wrapper for the HiveGuard security framework. One open-source bridge between HiveGuard's 20-invariant security spec and the world of MCP-compatible AI runtimes (OpenClaw, Claude Desktop, and any other client implementing the MCP standard).
Two operating modes (use either or both):
Mode A — Wrap a HiveGuard agent
You wrote (or installed) a Python agent extending BaseAgent. Mark methods with @expose_as_mcp_tool, hand the agent to HiveGuardMCPServer, and any MCP client can call those methods as tools — with HiveGuard's enforcement decorators still applied inside.
Mode B — Pure security gateway
No HiveGuard agent. The wrapper exposes primitive tools (fetch_url_safe, hash_data, validate_input, scrub_output) that any MCP client can call for risky operations. The gateway enforces HiveGuard invariants (INV-08, INV-11, INV-12, INV-16, INV-19) on those primitives, regardless of which framework the calling agent was built in.
This makes it possible for a TypeScript OpenClaw agent — or LangChain.js, Mastra, Hermes, an in-house TS agent, anything — to get HiveGuard-grade security on its risky operations without porting any code.
Install
pip install hiveguard-mcp-wrapper
Pulls in hiveguard-security-core, the official MCP SDK, pydantic, and uvicorn/starlette for the HTTP transport.
Quick start — Mode A
Wrap a HiveGuard agent:
from framework.agents.base_agent import BaseAgent
from framework.security.enforcement import (
audit_logged, sanitize_input, rate_limited,
)
from hiveguard_mcp_wrapper import HiveGuardMCPServer, expose_as_mcp_tool
class MyAgent(BaseAgent):
@expose_as_mcp_tool(name="echo")
@audit_logged()
@sanitize_input()
@rate_limited(max_calls=60, window_seconds=60)
async def echo(self, message: str) -> dict:
return {"echo": message}
agent = MyAgent("my-agent", agent_type="custom", port=3201)
server = HiveGuardMCPServer(agent=agent, name="my-agent-mcp")
from hiveguard_mcp_wrapper.transport_http import serve_http
serve_http(server, host="127.0.0.1", port=7301)
Now any MCP client can call echo (plus the default tools health, lifecycle_state, audit_log_recent, invariant_inventory).
Quick start — Mode B (gateway only)
from hiveguard_mcp_wrapper import HiveGuardMCPServer
from hiveguard_mcp_wrapper.gateway import build_gateway_tools
from hiveguard_mcp_wrapper.transport_http import serve_http
server = HiveGuardMCPServer(
agent=None,
name="hiveguard-gateway",
gateway_tools=build_gateway_tools(),
)
serve_http(server, host="127.0.0.1", port=7301)
Now any MCP client can call fetch_url_safe, hash_data, validate_input, scrub_output — all enforcing HiveGuard invariants.
OpenClaw integration
Add to your OpenClaw MCP Registry config:
{
"mcps": {
"hiveguard": {
"url": "http://127.0.0.1:7301/mcp",
"transport": "http"
}
}
}
Restart OpenClaw. The HiveGuard tools are now first-class tools in OpenClaw. Use them like any other tool. Same pattern works for LangChain.js, Mastra, Hermes, and any other MCP-compatible host.
CLI
The hiveguard-mcp-serve command starts the wrapper without writing any code:
# Mode A — wrap an agent
hiveguard-mcp-serve --agent my_pkg.agents:MyAgent --port 7301
# Mode B — gateway only
hiveguard-mcp-serve --gateway-only --port 7301
# Both modes on the same server
hiveguard-mcp-serve --agent my_pkg.agents:MyAgent --with-gateway --port 7301
# Network exposure (auto-requires HIVEGUARD_MCP_TOKEN env var)
HIVEGUARD_MCP_TOKEN=$(openssl rand -hex 32) \
hiveguard-mcp-serve --gateway-only --bind 0.0.0.0 --port 7301
What gets enforced (the security model)
The wrapper applies multiple layers of defense for every request:
- Header validation — rejects request smuggling (CL+TE conflicts), unknown content types, malformed transfer-encoding
- Body size cap — 256 KiB default at server layer, 4 MiB at HTTP transport layer (configurable via env)
- Bearer auth — required on non-loopback bind. Token compared in constant time. After 5 failed attempts in 60s, source blocked for 5 minutes.
- Strict JSON parsing — capped at 24 levels of nesting, 100k keys per object/array. Malformed UTF-8 rejected.
- Concurrency cap — 8 in-flight tool calls per identity by default
- Tool timeout — 30s wall-clock per tool call (configurable, per-tool override)
- Lifecycle gate — calls to agents in FROZEN / ESCALATED / DECOMMISSIONED state rejected with structured error
- Output scrubbing — recursive scan for sensitive substrings (
api_key,password,secret,token,credential,private_key,session_id,authorization,bearer,cookie,csrf,x-auth,aws_*). Belt-and-braces over INV-08. - Error scrubbing — exception messages NEVER leak to the client. Stack traces NEVER leak. Internal-error responses are generic.
- Audit log — every auth failure, every invariant block, every tool call logged in structured JSON with PII scrubbed.
See SECURITY.md for the full threat model + hardening checklist.
How the tests stay honest
The test suite is split into:
- Unit tests for each module (decorator, hardening primitives, error mapping)
- Integration tests for the full request pipeline
- Red-team tests that simulate adversarial inputs across 6 attack directions: external observer (T1), auth bypass (T2), input poisoning (T3), output exfiltration (T4), resource exhaustion (T5), privilege escalation (T6)
All 113 tests pass on every commit. If you find a way around the wrapper's defenses, please report it via security@ubava.ee — we'll add a regression test, fix it, and credit you.
# Run the test suite
pytest -v
# With coverage
pytest --cov=hiveguard_mcp_wrapper --cov-report=html
Configuration via environment
| Variable | Default | Purpose |
|---|---|---|
HIVEGUARD_MCP_TOKEN | (unset) | Bearer auth token. Required for non-loopback bind. |
HIVEGUARD_MCP_MAX_BODY_BYTES | 262144 | Max request body size at server layer |
HIVEGUARD_MCP_TOOL_TIMEOUT_S | 30.0 | Max wall-clock per tool call |
HIVEGUARD_MCP_MAX_CONCURRENT_PER_TOKEN | 8 | In-flight cap per identity |
Relationship to the HiveGuard family
hiveguard-security-core ← The 20-invariant spec + 12 enforced decorators
+ BaseAgent + lifecycle. Open-source MIT.
hiveguard-mcp-wrapper ← THIS repo. Bridges security-core agents to
MCP-compatible runtimes. Open-source MIT.
hiveguard-agents ← Commercial. Pre-built agents (Scout, Analyst,
Fixer, WebScout). Tumbler Vaults, BDP,
JurisdictionEngine. Sold as managed service
via ubava.ee.
For commercial use of the pre-built agents (Scout/Analyst/Fixer/WebScout) and for EU AI Act + GDPR compliance via UBava's relay, see ubava.ee and hiveguard.ee.
License
MIT. Use commercially. Attribute via the copyright notice.
Built by
UBava OÜ — Privacy-First Relay, Built for Europe.
- 📧 security@ubava.ee — security disclosures
- 🌐 hiveguard.ee — HiveGuard project site
- 🌐 ubava.ee — UBava relay + managed agents