# Provenza

Provenza is an MCP server for AI agents that verifies permissions and policies on tool calls, requests human approval, and maintains cryptographic audit trails.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: kironovlaziz-del
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/kironovlaziz-del/provenza/tree/HEAD/sdk/python
- Updated: 2026-10-27
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/provenza

## What it does

This MCP server routes agent tool calls through the Provenza governance platform. Before any tool runs, the server verifies permissions, registry rules, behavioral constraints, and circuit breakers. Unauthorized executions raise a denied error immediately. When human oversight is required, the call halts until an operator grants approval, allowing an exact rerun within an hour.

Provenza fails closed: if the remote control server drops offline, tools refuse to execute. In disconnected or standalone mode, the SDK stores actions inside a local hash-chained log. Only hashes of arguments and returned payloads are preserved in this log, preventing raw sensitive values from leaking into records.

Setup requires an active `PROVENZA_URL` alongside an enrollment secret `PROVENZA_TOKEN`. Private keys generate on the local host with `~/.config/provenza/agents/<name>.json` locked to permission mode 600, or directly inside the OS keychain via the optional `keychain` extra.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `PROVENZA_URL`, `PROVENZA_TOKEN`, `PROVENZA_AGENT_NAME` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env PROVENZA_URL=<PROVENZA_URL> --env PROVENZA_TOKEN=<PROVENZA_TOKEN> --env PROVENZA_AGENT_NAME=<PROVENZA_AGENT_NAME> --transport stdio python -- uvx provenza
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>

### Codex

**Platform CLI**
```bash
codex mcp add python --env PROVENZA_URL=<PROVENZA_URL> --env PROVENZA_TOKEN=<PROVENZA_TOKEN> --env PROVENZA_AGENT_NAME=<PROVENZA_AGENT_NAME> -- uvx provenza
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "python": {
            "command": "uvx",
            "args": [
                "provenza"
            ],
            "env": {
                "PROVENZA_URL": "<PROVENZA_URL>",
                "PROVENZA_TOKEN": "<PROVENZA_TOKEN>",
                "PROVENZA_AGENT_NAME": "<PROVENZA_AGENT_NAME>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "python": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "provenza"
            ],
            "env": {
                "PROVENZA_URL": "<PROVENZA_URL>",
                "PROVENZA_TOKEN": "<PROVENZA_TOKEN>",
                "PROVENZA_AGENT_NAME": "<PROVENZA_AGENT_NAME>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e PROVENZA_URL=<PROVENZA_URL> -e PROVENZA_TOKEN=<PROVENZA_TOKEN> -e PROVENZA_AGENT_NAME=<PROVENZA_AGENT_NAME> python uvx provenza
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>

## When to use it
- enforce access policies before an agent invokes sensitive tools
- pause agent operations until a human grants approval
- maintain a tamper-evident signed audit ledger for tool calls
- audit raw outbound network requests to model providers

## Example prompts
- Check with Provenza if the agent can delete the file at `/tmp/report.csv`
- Request human approval to dispatch an email to `cfo@example.com`
- Run the `zendesk.read` tool under policy supervision

## Similar
- [protect-mcp](https://affpapa.org/en/nevibecode/plugins/protect-mcp.md) — plugin · ★ 42780 repo stars
- [agent-governance](https://affpapa.org/en/nevibecode/skills/agent-governance.md) — skill · 9623 installs
- [Aegis — AI Agent Governance](https://affpapa.org/en/nevibecode/mcp/aegis-ai-agent-governance.md) — MCP server · ★ 18 repo stars
- [MCP Hangar](https://affpapa.org/en/nevibecode/mcp/mcp-hangar.md) — MCP server · ★ 17 repo stars
- [Assay MCP Server](https://affpapa.org/en/nevibecode/mcp/assay-mcp-server.md) — MCP server · ★ 16 repo stars
- [armorcodex](https://affpapa.org/en/nevibecode/plugins/armorcodex.md) — plugin · ★ 1596 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
