Vaara

What Vaara MCP server does

The Vaara MCP server governs actions taken by an agent or exposed tool function. Each call receives a risk score and a policy decision before the wrapped function body runs. The available outcomes are allow, deny, and escalate; both deny and escalate raise vaara.Blocked, so an unresolved human review does not continue as if the action had succeeded.

The server records the decision, call details, and resulting outcome in a persistent audit trail. Records are hash-chained and content-addressed, and signed receipts accompany the evidence. The default trail database is ~/.vaara/trail/audit.db, allowing records to survive process restarts. Per-tenant policy is part of the stated governance model.

This fits the Security category for deployments where an agent can change files, transfer funds, or invoke other consequential tools and the operator needs evidence that can be checked independently.

How it works

Install the Python package with pip install vaara. A Python function can be wrapped with @vaara.govern; alternatively, applications can use InterceptionPipeline directly and retain the decision object. The explicit pipeline accepts fields such as an agent ID, tool name, parameters, and agent confidence.

At interception time, Vaara calculates risk and compares the result with the active policy. The default balanced mode allows scores below 0.55 and denies scores above 0.85; uncertain or higher-risk calls can escalate. A shadow=True decorator mode observes decisions without enforcing them. Applications can call report_outcome after execution so later scoring can incorporate the observed result.

Receipts use canonicalized, signed data. The standalone verification flow can validate an evidence bundle without importing Vaara, and the browser receipt explorer checks Ed25519 signatures locally. Trail-head publication is opt-in through vaara trail publish-head.

Setup and configuration

Python 3.10 or newer is required. The base package includes the CLI, MCP proxy, and server, with cryptography, rfc8785, and cbor2 as runtime dependencies. An optional machine-learning classifier is available through pip install 'vaara[ml]'.

The macOS installation path is brew tap vaaraio/tap && brew install vaara, which installs the CLI and menu-bar app from source. A TypeScript client for the HTTP API is available separately as @vaara/client.

Use vaara mode list to inspect the available operating presets. Exporting the trail with vaara trail export signs the complete trail for third-party review.

Tools and capabilities

The Vaara MCP server provides or supports:

• Runtime interception of governed actions
• Risk scoring with policy-based allow, deny, or escalate decisions
• Shadow-mode observation without enforcement
• Hash-chained audit records stored on disk
• Signed receipts and exported evidence bundles
• Outcome reporting through report_outcome
• Offline receipt and bundle verification
• Optional publication of a trail head to a public transparency log

Limitations and notes

A valid signature does not prove that the signing key belongs to the expected party, that the signed statement is true, or that a timestamp is authoritative. One receipt also does not establish a complete history. An absent public transparency-log entry means only that the trail head was not published.

The default risk interval can be broad when there is no outcome history, which may cause escalation before the point estimate reaches a threshold. Reporting real outcomes narrows that interval. Publishing is disabled by default, and verification can be performed locally without sending the receipt to a service.