Metadata-Version: 2.4
Name: agentveil-mcp-proxy
Version: 0.7.22
Summary: Source-available MCP route for approval and local evidence on routed MCP tool calls
Author-email: Oleg Boiko <ob@agentveil.dev>
Maintainer-email: Oleg Boiko <ob@agentveil.dev>
License-Expression: BUSL-1.1
Project-URL: Homepage, https://agentveil.dev
Project-URL: Documentation, https://github.com/agentveil-protocol/agentveil-sdk/tree/main/packages/agentveil-mcp-proxy#readme
Project-URL: Repository, https://github.com/agentveil-protocol/agentveil-sdk
Project-URL: Issues, https://github.com/agentveil-protocol/agentveil-sdk/issues
Keywords: ai,agents,agent-control,runtime-gate,mcp,mcp-proxy,approval,evidence,routed-actions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentveil<0.8,>=0.7.19
Requires-Dist: mcp>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Dynamic: license-file

# 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`](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

```bash
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:

```bash
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][ops-passphrase].

Validate the local setup:

```bash
agentveil-mcp-proxy doctor
```

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

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

Then run the proxy:

```bash
agentveil-mcp-proxy run
```

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

```bash
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:

```bash
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

```json
{
  "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:

```bash
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](../../docs/DATA_HANDLING.md).

## 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.

[ops-passphrase]: ../../docs/MCP_PROXY_OPERATIONS.md#security-trade-offs-by-passphrase-source
