vaikora-guard-mcp 0.1.0

Model Context Protocol server that enforces deterministic policy on AI tool calls using the Vaikora policy engine.

Vaikora Guard MCP

A Model Context Protocol server that puts deterministic policy enforcement in front of every AI agent tool call.

---

What this does

Vaikora Guard MCP lets any MCP client (Claude Desktop, Claude Code, custom agents using the Anthropic SDK) call the Vaikora policy engine before executing a tool action. The agent describes what it wants to do, Vaikora evaluates the request against six deterministic content modules and the active policy set, and returns one of four outcomes with a SHA-256 audit receipt:

Outcome	Meaning
ALLOW	Action passes every policy, agent can proceed.
ALLOW_LOG	Action is permitted, but logged for audit review.
CONSTRAIN	Action is permitted with a modification (e.g. PII redaction).
BLOCK	Action violates a policy, agent must not proceed.

The server is a thin façade over the open-source vaikora-llm-gateway. All policy logic, audit storage, and threat intelligence enrichment live in the gateway. This MCP server adapts the MCP protocol to the gateway's HTTP API.

Why use it

Most MCP servers expose new capabilities to an agent. Vaikora Guard does the opposite: it adds a deterministic policy gate that an agent (or an orchestrator) consults before acting. Useful when:

• You ship AI agents to customers and need an audit trail per action.
• You want to enforce GRC controls (SOC analyst review, separation of duties, regulated-data handling) on actions an LLM proposes.
• You want a fail-closed posture when the policy engine is unreachable, so unsafe actions cannot slip past.

Install

pip install vaikora-guard-mcp

Requires Python 3.10 or newer. Installing the package creates a vaikora-guard-mcp CLI entry point that runs the MCP server over stdio.

Configure

Copy .env.example to .env and fill in:

VAIKORA_GATEWAY_URL=http://localhost:8000     # or your hosted Vaikora endpoint
VAIKORA_API_KEY=your-vaikora-api-key
VAIKORA_FAIL_CLOSED=true

Run a local vaikora-llm-gateway instance (Docker Compose recipe lives in that repo) or point at a hosted Vaikora endpoint your team operates.

Wire it into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "vaikora-guard": {
      "command": "vaikora-guard-mcp",
      "env": {
        "VAIKORA_GATEWAY_URL": "http://localhost:8000",
        "VAIKORA_API_KEY": "your-vaikora-api-key"
      }
    }
  }
}

Restart Claude Desktop. The vaikora-guard server will show up in the MCP indicator and Claude can call its tools.

Full Claude Code config example lives in examples/claude-code-config.json.

Tools exposed

Tool	Purpose
evaluate_action	Run a candidate action through the full Vaikora enforcement pipeline and return a decision.
check_module	Run a single content module (PII, jailbreak, injection, semantic, domain risk, email classification) against text.
get_policies	Return the current policy + entitlement configuration in the gateway.
write_audit	Append an entry to the Vaikora audit log after an action has executed.

Resources exposed

Resource	Purpose
vaikora://policies	JSON snapshot of the active policy + entitlement set.
vaikora://modules	List of the six built-in content modules the gateway supports.

Example call from an agent

# Pseudocode for an agent using the MCP tools
result = await mcp.call_tool(
    "evaluate_action",
    {
        "action": "DELETE FROM customers WHERE country = 'US'",
        "context": {"target_system": "prod_db", "agent_id": "support-bot-01"},
    },
)
# result is JSON. Example shape:
# {
#   "decision": {"outcome": "BLOCK", "matched_policy": "injection_detection", ...},
#   "receipt_id": "sha256:abc...",
#   "pipeline": [...],
#   "latency_ms": 47
# }
if result["decision"]["outcome"] in ("BLOCK",):
    raise PolicyViolation(result["decision"]["reason"])

Logging and visibility

The server emits structured logs so operators can watch it live, post-hoc, and parse it with their existing tooling.

Where logs land:

Destination	Purpose	Format
stderr	Live tail (Claude Desktop, Claude Code, and any MCP client capture this)	JSON or human-readable
Rotating file	Post-hoc analysis, long-running operators	Same format as stderr
stdout	Reserved for the MCP JSON-RPC protocol. Never written to.	n/a

Default file paths:

Platform	Path
macOS	~/Library/Logs/vaikora-guard-mcp/vaikora-guard-mcp.log
Linux	${XDG_CACHE_HOME:-~/.cache}/vaikora-guard-mcp/vaikora-guard-mcp.log
Windows	%LOCALAPPDATA%\vaikora-guard-mcp\logs\vaikora-guard-mcp.log

Override the path with VAIKORA_LOG_FILE=/your/path/vaikora.log.

What gets logged:

Event	Level	Fields
mcp.boot	INFO	gateway_url, fail_closed, log_level, log_file, log_json
mcp.transport.ready	INFO	transport
mcp.list_tools / mcp.list_resources	DEBUG	(counts)
mcp.read_resource.start / .done / .error	INFO / ERROR	uri, latency_ms, body_bytes
mcp.call_tool.start / .done / .error	INFO / ERROR	tool, arg_keys, arg_preview, latency_ms, outcome, receipt_id, matched_policy
vaikora.http.ok / vaikora.http.error	INFO / WARNING	method, path, status, latency_ms, outcome, receipt_id
vaikora.fallback	ERROR	outcome, matched_policy, latency_ms, receipt_id, fail_closed
mcp.shutdown	INFO	(none)

Every tool call carries a per-call request_id correlation token that threads through every log line for that call, so operators can pivot on a single id to see the whole flow.

Sensitive data handling: API keys, JWTs, Authorization: Bearer … headers, basic-auth URL credentials, and GitHub-style tokens are scrubbed from log output. The redactor walks dicts recursively, so nested headers inside metadata also get scrubbed.

Tail it live (macOS):

tail -f "$HOME/Library/Logs/vaikora-guard-mcp/vaikora-guard-mcp.log" | jq .

Switch to human-readable mode for local debugging:

export VAIKORA_LOG_JSON=false
export VAIKORA_LOG_LEVEL=DEBUG
vaikora-guard-mcp

Fail-closed by default

If the Vaikora gateway is unreachable, the server returns a synthetic BLOCK decision with matched_policy="gateway_unreachable". Set VAIKORA_FAIL_CLOSED=false for fail-open behavior. Fail-closed is the recommended posture for production agents handling regulated data.

Develop

git clone https://github.com/Data443/vaikora-guard-mcp.git
cd vaikora-guard-mcp
pip install -e ".[dev]"
pytest -q
ruff check .

Run the server locally against a real gateway:

export VAIKORA_GATEWAY_URL=http://localhost:8000
export VAIKORA_API_KEY=...
vaikora-guard-mcp

The server will speak MCP over stdio. To talk to it interactively, point an MCP-compatible client at the same command.

How it relates to Vaikora

Vaikora is Data443's AI runtime control product. It sits between an AI agent and the world, evaluating every proposed action against deterministic policies before execution. Vaikora ships in two shapes:

1. HTTP gateway: vaikora-llm-gateway, an open-source reverse proxy that enforces policy on LLM provider traffic (OpenAI, Anthropic, Gemini, OpenRouter).
2. MCP server: this repo, which exposes the same enforcement engine to MCP clients so agent runtimes can call it directly.

Both share the same policy store, decision shape, and audit log. Pick whichever surface fits your agent runtime, or run both side by side.

Learn more about Vaikora: vaikora.com | Vaikora docs | Data443 AI runtime control.

License

MIT. See LICENSE.

Support

• Issues: github.com/Data443/vaikora-guard-mcp/issues
• Email: [e-mail]
• Vaikora docs: vaikora.com/docs

Vaikora Guard MCP integrates with the Claude API, Claude Code, and the Anthropic SDK. The integration is built on the open Model Context Protocol and does not imply any endorsement by Anthropic.