Provenza — Claude Code MCP server: what it does, how to install
Provenza is an MCP server for AI agents that verifies permissions and policies on tool calls, requests human approval, and maintains cryptographic audit trails.
Apache-2.0 ★ 5 updated 2026-10-27
claude mcp add --env PROVENZA_URL=<PROVENZA_URL> --env PROVENZA_TOKEN=<PROVENZA_TOKEN> --env PROVENZA_AGENT_NAME=<PROVENZA_AGENT_NAME> --transport stdio python -- uvx provenzaWhat Provenza 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.
What it helps with
- 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 for the agent
- Check with Provenza if the agent can delete the file at
/tmp/report.csv - Request human approval to dispatch an email to
[email protected] - Run the
zendesk.readtool under policy supervision
How to install Provenza
Platform CLI
claude mcp add --env PROVENZA_URL=<PROVENZA_URL> --env PROVENZA_TOKEN=<PROVENZA_TOKEN> --env PROVENZA_AGENT_NAME=<PROVENZA_AGENT_NAME> --transport stdio python -- uvx provenzaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>
Platform CLI
codex mcp add python --env PROVENZA_URL=<PROVENZA_URL> --env PROVENZA_TOKEN=<PROVENZA_TOKEN> --env PROVENZA_AGENT_NAME=<PROVENZA_AGENT_NAME> -- uvx provenzaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add -e PROVENZA_URL=<PROVENZA_URL> -e PROVENZA_TOKEN=<PROVENZA_TOKEN> -e PROVENZA_AGENT_NAME=<PROVENZA_AGENT_NAME> python uvx provenzaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from provenza <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Provenza
How to install Provenza in Claude Code?
Run this command in your terminal: claude mcp add provenza -e PROVENZA_URL=<PROVENZA_URL> -e PROVENZA_TOKEN=<PROVENZA_TOKEN> -- uvx provenza.
What does Provenza do?
It intercepts agent tool executions, validates permissions against organizational policies, stops calls needing human consent, and cryptographically signs audit receipts.
Does Provenza log prompt data and tool payloads?
No, local audit logs and proxy checks only retain hashes and body sizes rather than raw prompt text or argument contents.