BarzelVault MCP is a Model Context Protocol server that governs every tool call an AI agent makes before any side effect reaches your application. It is mounted directly onto your Express app and integrates with your existing auth, storage, and risk services.

AI Agent (Claude / GPT / custom LLM) │ MCP protocol (SSE + JSON-RPC) ▼ ┌──────────────────────────────────────────────────────────────┐ │ BarzelVault MCP v5 │ │ │ │ Auth → Policy Engine → Guardrails → Circuit Breaker │ │ → Tool Registry → Resilience → Metrics → Memory │ │ → Streaming Protocol → Observability │ └──────────────────────────┬───────────────────────────────────┘ │ Application Backend Services Version History Version Highlights v1 12 core tools, SSE transport, JWT + API key auth v2 Tool Registry, Error System, Observability, Guardrails, Streaming v3 23-bug security audit: empty token, double-server, recursive sanitize, byte truncation, tenant-scoped rate limits v4 Policy Engine, Plugin Marketplace, Agent Memory, Risk Router + 20 bug fixes v5.1 (current) Polish pass: fixed weighted-avg latency bug, NaN pct guard, exhaustive switch, duplicate-param confusion, console.info consistency, module-level constants, isErrorResult type guard, clampPct, production signing secret warning v5 New Capabilities

Circuit Breaker & Retry Engine (circuitBreaker.ts) Per-tool, per-tenant state machine: CLOSED → OPEN → HALF_OPEN → CLOSED Exponential backoff with ±30% jitter — prevents thundering herd Retries only retryable: true errors — write tools (execute_action, approve_action) retry at most once Fallback chain: if the primary tool's circuit is open, transparently tries registered fallbacks Admin endpoint to manually reset a circuit External Tool Registry (externalToolRegistry.ts) Register any HTTPS endpoint as an MCP tool via POST /mcp/tools/register Full SSRF protection: blocks localhost, RFC1918, link-local, AWS metadata IPs HMAC-SHA256 request signing on every outbound call No HTTP redirect following (redirect: "error") Response size cap (default 64 KiB) with streaming body reader API keys stored and redacted in all public views

Metrics Collector (metricsCollector.ts) Per-tool latency histograms: p50, p95, p99, max Failure rate and error code breakdown Risk-score distribution per tool Time-window aggregation: 5m, 15m, 1h, 6h, 24h, 7d Dashboard summary: top tools by volume, top by latency, error hotspots Time-series buckets for charting (configurable bucket count)

Structured Streaming Protocol (streamingProtocol.ts) Typed SSE events: progress | partial | result | error | done progress events carry step name, status, optional percentage, and timestamp partial events carry sequence numbers for reassembly StreamWriter class — type-safe, write-safe (guards writableEnded) Per-step name sanitization (strips control characters) 64 KiB per-event size cap

Tool Management Endpoints (v5) GET /mcp/tools/versions/:toolName — list all registered versions POST /mcp/tools/:name/enable — re-enable a disabled tool POST /mcp/tools/:name/disable — disable at runtime (non-destructive) POST /mcp/tools/register — register an external HTTP tool DELETE /mcp/tools/:name — deregister an external tool GET /mcp/tools/external — list external tool registrations Quick Start

Copy BarzelVault MCP into your project

cp -r "BarzelVault MCP/" src/mcp/

Wire into Express

import { registerMcpRoutes } from "./mcp/server"; app.use(express.json()); registerMcpRoutes(app); Required environment variables (v5):

Variable Purpose PLUGIN_SIGNING_SECRET HMAC secret for plugin manifest signatures BV_OUTBOUND_SIGNING_SECRET HMAC secret for outbound external tool requests File Structure (v5 — 16 files, ~5,500 lines) BarzelVault MCP/ ├── server.ts # Express routes + dispatch pipeline (1091 lines) ├── tools.ts # 12 built-in tool definitions (488 lines) ├── toolRegistry.ts # Registry: versioning, enable/disable, manifests (220 lines) ├── mcpErrors.ts # 25 typed error codes + classifier + sanitizer (235 lines) ├── guardrails.ts # Timeout, rate limiting, input size (233 lines) ├── observability.ts # Tracing, ring buffer, structured logging (223 lines) ├── mcpPolicyEngine.ts # Pre-handler call authorization (339 lines) ├── pluginMarketplace.ts # Plugin lifecycle + sandbox (394 lines) ├── agentMemory.ts # Two-tier KV: session + persistent (321 lines) ├── riskRouter.ts # Safest-tool recommendation engine (226 lines) │ │ ── v5 NEW FILES ── ├── circuitBreaker.ts # Circuit breaker, retry, fallback (330 lines) ├── metricsCollector.ts # Per-tool metrics + dashboard (310 lines) ├── externalToolRegistry.ts# HTTP-proxy tool registration (340 lines) ├── streamingProtocol.ts # Typed SSE streaming (235 lines) │ │ ── Unchanged ── ├── resources.ts # 7 MCP read-only resources └── prompts.ts # 3 MCP reasoning prompts All REST Endpoints (v5 — 33 total) Core MCP Method Path Description GET /mcp/sse Open SSE session POST /mcp/messages Dispatch JSON-RPC message GET /mcp/info Server + tool manifest GET /mcp/observability Call trace ring buffer GET /mcp/stream/:toolName 405 — use POST POST /mcp/stream/:toolName Streaming tool execution Policy Engine Method Path Description GET /mcp/policy/list All policies GET /mcp/policy/stats Daily call counts POST /mcp/policy Register custom policy DELETE /mcp/policy/:id Disable policy Plugin Marketplace Method Path Description GET /mcp/plugins List plugins POST /mcp/plugins/submit Submit plugin POST /mcp/plugins/:id/:version/approve Approve POST /mcp/plugins/:id/:version/activate Activate POST /mcp/plugins/:id/:version/suspend Suspend Agent Memory Method Path Description GET /mcp/memory/stats Memory utilization DELETE /mcp/memory Purge tenant memory (GDPR) GET /mcp/memory/:agentId List agent memory POST /mcp/memory/:agentId Write memory entry DELETE /mcp/memory/:agentId/:key Delete entry Risk Router Method Path Description GET /mcp/router/recommend Safest tool for intent GET /mcp/router/heatmap Risk score map v5 External Tools Method Path Description POST /mcp/tools/register Register external HTTP tool DELETE /mcp/tools/:name Deregister GET /mcp/tools/external List registrations v5 Metrics Method Path Description GET /mcp/metrics Dashboard summary GET /mcp/metrics/:toolName Per-tool summary GET /mcp/metrics/:toolName/series Time-series buckets v5 Circuit Breakers Method Path Description GET /mcp/circuits All circuit snapshots POST /mcp/circuits/:toolName/reset Manual reset v5 Tool Management Method Path Description GET /mcp/tools/versions/:toolName Version list POST /mcp/tools/:name/enable Enable tool POST /mcp/tools/:name/disable Disable tool Documentation Index File Contents README.md Overview, quick start, endpoint index ARCHITECTURE.md System design, dispatch pipeline, security layers TOOLS_REFERENCE.md All 12 tools + resources + prompts API_REFERENCE.md Every REST endpoint: request/response shapes V5_MODULES.md Deep dive: Circuit Breaker, External Tools, Metrics, Streaming SECURITY.md Threat model, SSRF protection, defense matrix, hardening checklist ERROR_CODES.md All 25 error codes, retryability, handling guidance CONFIGURATION.md Env vars, guardrail tuning, rate limits, metrics GC