agentveil-mcp-proxy 0.7.22

Source-available MCP route for approval and local evidence on routed MCP tool calls

agentveil-mcp-proxy

agentveil-mcp-proxy is the public AgentVeil route for MCP tool calls today. It wraps a downstream MCP server and applies AgentVeil policy to calls that pass through the proxy: allow, approval-required, or block, with bounded local evidence.

This package is source-available under the Business Source License 1.1. See LICENSE.

Scope

MCP Proxy controls only MCP tool calls that are explicitly routed through agentveil-mcp-proxy.

• It does not control host shell commands.
• It does not control IDE-native file edits.
• It does not control direct git, pip, deploy, or package-manager commands.
• It does not create a Cursor, Codex, Claude, or desktop host lock.
• Actions not routed through the proxy are not classified or logged.

Use credential custody, egress boundaries, or API gates when an action must be controlled below the agent process. Those boundary patterns are preview and design-partner work, not general public release paths in this package.

Install

pip install agentveil-mcp-proxy

This installs the agentveil-mcp-proxy console script. The core agentveil SDK is installed as a dependency.

Quick Start

Create a local proxy identity, config, and control grant:

agentveil-mcp-proxy init

By default init creates an encrypted identity. Provide a passphrase interactively, via --passphrase-file, or via the AVP_PROXY_PASSPHRASE environment variable. See Operations: Security trade-offs by passphrase source.

Validate the local setup:

agentveil-mcp-proxy doctor

For a local first run without installing another MCP server, configure the built-in sandboxed filesystem downstream:

agentveil-mcp-proxy init --quickstart-filesystem ./sandbox
agentveil-mcp-proxy doctor --full
agentveil-mcp-proxy smoke

Then run the proxy:

agentveil-mcp-proxy run

For a real downstream server, write downstream.command and downstream.args with the helper:

agentveil-mcp-proxy downstream set \
  --name filesystem \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg /Users/me/work

Configure An MCP Client

Point your MCP client at agentveil-mcp-proxy run instead of directly at the downstream MCP server. The proxy reads downstream server config from ~/.avp/mcp-proxy/config.json.

If you installed into a virtual environment, point command at the full path of agentveil-mcp-proxy inside that environment.

To print copy-pasteable client config without editing application files:

agentveil-mcp-proxy client-config print
agentveil-mcp-proxy client-config print --client cursor --proxy-command "$(which agentveil-mcp-proxy)"
agentveil-mcp-proxy client-config print --json

This is dry-run only: it writes to stdout, not ~/.cursor, Claude Desktop, or other application config directories.

Generic stdio configuration

{
  "mcpServers": {
    "agentveil-mcp-proxy": {
      "command": "agentveil-mcp-proxy",
      "args": ["run"]
    }
  }
}

Local Evidence

Approval-gated routed tool calls write durable local records to the MCP Proxy evidence store under the configured AVP home directory. Export an evidence bundle for offline checks:

agentveil-mcp-proxy export-evidence ./bundle.json
agentveil-mcp-proxy verify ./bundle.json --trusted-signer-did did:key:...

Raw MCP arguments, prompts, outputs, tokens, source code, secrets, and private logs remain local by default. Runtime decisions should use bounded metadata and hashes. See Data Handling.

Built-In Policy Packs

init --policy-pack <name> selects a starter pack:

Pack	Default behavior
default	Tool calls are forwarded to the Runtime Gate path.
github	Reads allowed; writes forwarded to Runtime Gate; destructive verbs require approval.
filesystem	Reads allowed; writes require approval; destructive verbs are denied.
shell	Shell tool calls require approval when routed through the proxy.

Built-in packs are starter templates, not exhaustive policies. Review patterns for your specific downstream server.

CLI Commands

Command	Purpose
init	Create encrypted identity, config, and control grant.
init --quickstart-filesystem <path>	Configure the built-in filesystem downstream for local first run.
doctor	Validate local files and control grant.
doctor --full	Launch downstream and verify MCP initialize / tools/list.
downstream set	Write downstream MCP server config without hand-editing JSON.
client-config print	Print MCP client config snippets.
smoke	Launch downstream and run a local MCP smoke check.
run	Run stdio passthrough for MCP clients.
export-evidence <path>	Export a local evidence bundle.
verify <bundle.json>	Verify a previously exported bundle.
events list --limit 20	Print recent privacy-bounded evidence records.
evidence-summary	Print local evidence counts.

Relationship To AgentVeil

agentveil-mcp-proxy is one routed action path for AgentVeil. The root agentveil SDK contains identity, delegation, Runtime Gate client helpers, receipt helpers, and framework adapters. This package is the MCP route only.