agentveil-mcp-proxy

agentveil-mcp-proxy is the public AgentVeil package for project connector setup and routed MCP action control. It works alongside agent runtimes and applies the same proof + redirect loop to configured action paths: attempt, decision, controlled path when available, local proof.

It includes two public surfaces:

1. Project connector setup for supported agent clients such as Cursor, Claude Code, Codex, and Gemini CLI. Connectors install managed project-local hooks and MCP route config so supported native agent mutations can be blocked with redirect guidance toward the AgentVeil MCP route. Hermes CLI is supported as a controlled MCP launch profile.
2. Core MCP Proxy, which wraps a downstream MCP server and applies AgentVeil policy to calls that pass through the proxy: allow, approval-required, redirect, hard-block, with bounded local evidence.

This package is free to use in production for internal and non-competing use. The Business Source License 1.1 limits offering this package, or a modified version, as a competing hosted or embedded service. See LICENSE for the complete Additional Use Grant.

Scope

AgentVeil control is scoped to configured project connectors and routed MCP calls.

• Project connectors can control supported native agent mutation tools only inside configured projects and supported client hook paths.
• The Core MCP Proxy controls only MCP tool calls that are explicitly routed through agentveil-mcp-proxy.
• The Core MCP Proxy alone does not control host shell commands or IDE-native file edits.
• AgentVeil does not control direct human terminal commands, direct git, pip, deploy, or package-manager commands outside configured AgentVeil paths.
• It does not create a Cursor, Claude Code, Codex, Gemini CLI, Hermes, or desktop-wide lock.
• Actions outside configured connectors and routed proxy calls 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.

Updating an existing filesystem CA policy

Package installation does not rewrite saved policy rules. To explicitly add stage/restore rules and approval-gated cleanup to an existing filesystem policy, preview the change:

agentveil-mcp-proxy upgrade-ca-policy --home <project-avp-home> --json

Review added_rule_ids, stop the proxy and any config editors, then apply with the config_sha256 returned by that preview:

agentveil-mcp-proxy upgrade-ca-policy --home <project-avp-home> --apply --expected-config-sha256 <preview-hash> --json

The command appends the versioned CA rules, preserves other config fields and user rules, and saves the original bytes beside the config in a hash-named .bak file. A changed config hash, conflicting rule ID or symlink stops the operation. Restart the proxy afterward. The rules require a working CA binding; they do not activate an unavailable provider or authorize irreversible cleanup. Generic and semantic forms share restrictions for the explicitly matched CA operation IDs. Older runtimes that do not support this matcher reject the updated config; restore the saved config before downgrading.

What This Package Adds

Agent runtimes execute agents and expose tools. agentveil-mcp-proxy adds a local action-control layer around configured paths:

• project connectors for supported runtime hooks;
• routed MCP policy and approval;
• bounded local evidence;
• starter policy packs for common routed action types.

It does not replace Cursor, Claude Code, Codex, autonomous frameworks, or custom MCP clients.

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

Cursor project connector

pip install agentveil-mcp-proxy
agentveil-mcp-proxy setup cursor --choose-folder

Choose the project folder to protect, then reopen / reload Cursor for that project. See Cursor project-local hooks.

Some Cursor versions may require enabling the managed agentveil-mcp-proxy MCP server once in Tools & MCPs after reload.

Claude Code project connector

pip install agentveil-mcp-proxy
agentveil-mcp-proxy setup claude-code --choose-folder --yes

Choose the project folder to protect, then reopen / reload Claude Code for that project. See Claude Code Connector — Scope and Quickstart.

Codex project connector

pip install agentveil-mcp-proxy
agentveil-mcp-proxy setup codex --choose-folder --yes

Choose the project folder to protect, then open / restart Codex for that project. Codex asks you to trust the AgentVeil project hook once; until hook evidence is observed, setup status --client codex remains advisory, not protected.

Gemini CLI project connector

pip install agentveil-mcp-proxy
agentveil-mcp-proxy setup gemini-cli --choose-folder --yes

Choose the project folder to protect, then open / restart Gemini CLI for that project. Gemini CLI asks you to trust the project folder before it loads local settings, hooks, and MCP servers.

Hermes CLI controlled MCP profile

Hermes CLI is launched through AgentVeil rather than installed as a persistent project hook:

pip install agentveil-mcp-proxy
agentveil-mcp-proxy launch --profile hermes-cli --choose-folder -- \
  hermes chat -q "Create a project note"

This configures a project-local Hermes home and routes Hermes to the AgentVeil MCP tools. Routed reads, writes, approval, sandbox boundaries, redirect guidance, and local proof use the shared AgentVeil control layer. Native Hermes tools are limited by profile settings; AgentVeil does not claim host-wide control of Hermes or the machine.

Walkable example after setup

In the configured project:

1. Ask the agent to read project files. Routed reads should allow.
2. Ask the agent to write a file. The configured connector should stop the native mutation with redirect guidance; the agent should then use the controlled MCP route, where risky writes require approval.
3. Open the approval page and review bounded proof details.
4. Confirm local proof:

agentveil-mcp-proxy events show --last

Core MCP Proxy

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.

Any MCP-speaking client can use this route when it is explicitly configured to call agentveil-mcp-proxy run. That is routed MCP control, not global control of the client or host.

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.

Inspect recent bounded decisions:

agentveil-mcp-proxy events show --last
agentveil-mcp-proxy events show --last --json
agentveil-mcp-proxy events show --last --verify

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:

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

CLI Commands

Connect To AgentVeil Console (Optional)

If you use the hosted AgentVeil Console, you can connect this machine with a short device-pairing flow:

agentveil-mcp-proxy login
agentveil-mcp-proxy logout

login prints a verification URL and a short code, attempts to open the URL in your browser (use --no-open for headless/terminal use), and stores a single device token locally at ~/.avp/console/device-token.json with owner-only 0600 permissions. logout revokes that token with the Console and removes the local file.

Connecting to Console is optional. It does not activate paid, Team, policy, or project-sync features, and it does not change how routed MCP calls or project connectors are controlled locally. The stored token grants only the bounded_summary_upload scope.

After login, successful project connector setup and explicit setup status for Codex, Claude Code, Cursor, or Gemini CLI may send one bounded project connection summary to the Console. The upload includes a bounded local report field, private_guardrails_status, with one of active, inactive, or unavailable. That value reflects only the installed local paid provider state; it does not grant entitlement. Console combines this report with server-owned workspace capability before showing Active. Without a stored credential this step is a silent no-op: no network request, no provider discovery, and no extra CLI output. Boundary: the upload is best-effort and isolated from local setup; Console rejection or outage does not change setup results, exit codes, connector files, or Approval Center behavior.

Relationship To AgentVeil

agentveil-mcp-proxy is the public package for AgentVeil project connectors and the routed MCP action-control path. The root agentveil SDK contains identity, delegation, Runtime Gate client helpers, receipt helpers, and framework adapters.