Skip to content

Commit bddf600

Browse files
oleg-bkoleg-bk
committed
docs(mcp-proxy): add subproject README and module entry
Add the agentveil_mcp_proxy subproject README, expose python -m agentveil_mcp_proxy, and include the proxy README as package data. The module entry uses a __name__ guard so python -m works while import sanity checks remain side-effect free. Implemented with assistance from Codex.
1 parent 3577e4b commit bddf600

3 files changed

Lines changed: 303 additions & 0 deletions

File tree

‎agentveil_mcp_proxy/README.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
# agentveil-mcp-proxy
2+
3+
MCP transport proxy for **AgentVeil Protocol** - Action Control Plane that
4+
wraps a downstream MCP server with runtime decision gating, human approval
5+
routing, durable signed evidence, and replay defense. It is the intercepting
6+
transport adapter for IDE MCP clients such as Claude Desktop, Cursor, Cline,
7+
Windsurf, and VS Code.
8+
9+
This is one integration adapter for AVP. The trust/control/evidence engine and
10+
identity foundation live in the core `agentveil` SDK; this package is the
11+
MCP-transport adapter.
12+
13+
- **Status:** stdio passthrough for one downstream MCP server per proxy
14+
instance. Encrypted identity by default, durable approval evidence, signed
15+
receipts, offline bundle verification.
16+
- **Package:** bundled inside `agentveil` on PyPI. Console script
17+
`agentveil-mcp-proxy` registered automatically.
18+
- **License:** MIT.
19+
20+
## Install
21+
22+
```bash
23+
pip install agentveil
24+
```
25+
26+
This installs the core `agentveil` SDK plus the `agentveil-mcp-proxy` console
27+
script. No additional extras are required.
28+
29+
## Quick Start
30+
31+
Create a local proxy identity, config, and control grant:
32+
33+
```bash
34+
agentveil-mcp-proxy init
35+
```
36+
37+
By default `init` creates an encrypted identity. Provide a passphrase
38+
interactively, via `--passphrase-file`, or via the `AVP_PROXY_PASSPHRASE`
39+
environment variable. See
40+
[Operations: Security trade-offs by passphrase source][ops-passphrase].
41+
42+
Validate the local setup:
43+
44+
```bash
45+
agentveil-mcp-proxy doctor
46+
```
47+
48+
Edit `~/.avp/mcp-proxy/config.json` to point `downstream.command` and
49+
`downstream.args` at the MCP server you want to wrap. Then run:
50+
51+
```bash
52+
agentveil-mcp-proxy run
53+
```
54+
55+
The proxy reads stdio from your MCP client, classifies tool calls, evaluates
56+
them through AVP Runtime Gate, routes approval prompts to a local browser UI
57+
when needed, persists durable signed evidence, and forwards approved calls to
58+
the downstream server.
59+
60+
### Supported invocation paths
61+
62+
| Command | Status |
63+
|---|---|
64+
| `agentveil-mcp-proxy run` | **canonical** - console script passthrough mode |
65+
| `python3 -m agentveil_mcp_proxy run` | supported - module form |
66+
67+
## Configure Your MCP Client
68+
69+
Instead of pointing your IDE directly at a downstream MCP server, point the IDE
70+
at `agentveil-mcp-proxy`. The proxy reads the actual downstream command from
71+
`~/.avp/mcp-proxy/config.json` and wraps that server with Runtime Control Layer
72+
checks.
73+
74+
If you installed into a virtual environment, point `command` at the full path of
75+
`agentveil-mcp-proxy` inside that environment (`which agentveil-mcp-proxy`).
76+
77+
### Claude Desktop
78+
79+
`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or
80+
`%APPDATA%/Claude/claude_desktop_config.json` on Windows:
81+
82+
```json
83+
{
84+
"mcpServers": {
85+
"filesystem-gated": {
86+
"command": "agentveil-mcp-proxy",
87+
"args": ["run"]
88+
}
89+
}
90+
}
91+
```
92+
93+
The proxy reads downstream server config from
94+
`~/.avp/mcp-proxy/config.json`:
95+
96+
```json
97+
{
98+
"downstream": {
99+
"name": "filesystem",
100+
"command": "npx",
101+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/work"]
102+
}
103+
}
104+
```
105+
106+
### Cursor
107+
108+
`.cursor/mcp.json` in your project root:
109+
110+
```json
111+
{
112+
"mcpServers": {
113+
"github-gated": {
114+
"command": "agentveil-mcp-proxy",
115+
"args": ["run"]
116+
}
117+
}
118+
}
119+
```
120+
121+
`~/.avp/mcp-proxy/config.json`:
122+
123+
```json
124+
{
125+
"downstream": {
126+
"name": "github",
127+
"command": "github-mcp-server",
128+
"args": []
129+
}
130+
}
131+
```
132+
133+
### Windsurf
134+
135+
`~/.codeium/windsurf/mcp_config.json`:
136+
137+
```json
138+
{
139+
"mcpServers": {
140+
"filesystem-gated": {
141+
"command": "agentveil-mcp-proxy",
142+
"args": ["run"]
143+
}
144+
}
145+
}
146+
```
147+
148+
`~/.avp/mcp-proxy/config.json`:
149+
150+
```json
151+
{
152+
"downstream": {
153+
"name": "filesystem",
154+
"command": "npx",
155+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/work"]
156+
}
157+
}
158+
```
159+
160+
### VS Code (Copilot)
161+
162+
`.vscode/mcp.json` in your workspace:
163+
164+
```json
165+
{
166+
"servers": {
167+
"filesystem-gated": {
168+
"command": "agentveil-mcp-proxy",
169+
"args": ["run"]
170+
}
171+
}
172+
}
173+
```
174+
175+
`~/.avp/mcp-proxy/config.json`:
176+
177+
```json
178+
{
179+
"downstream": {
180+
"name": "filesystem",
181+
"command": "npx",
182+
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/work"]
183+
}
184+
}
185+
```
186+
187+
### Any MCP Client (generic stdio)
188+
189+
```bash
190+
agentveil-mcp-proxy run
191+
```
192+
193+
## Environment Variables
194+
195+
| Variable | Default | Description |
196+
|---|---|---|
197+
| `AVP_HOME` | `~/.avp` | Override the proxy home directory. Identity, config, control grant, and evidence DB live here. |
198+
| `AVP_PROXY_PASSPHRASE` | (unset) | Encrypted-identity passphrase. **See [Security trade-offs by passphrase source][ops-passphrase]** - env vars can leak through `/proc/<pid>/environ` and `ps eww`; prefer `--passphrase-file` for automated and CI setups. |
199+
200+
## Built-In Policy Packs
201+
202+
`init --policy-pack <name>` selects a starter pack:
203+
204+
| Pack | Default behavior |
205+
|---|---|
206+
| `default` | All tool calls forwarded to AVP Runtime Gate. |
207+
| `github` | Reads allowed; writes forwarded to Runtime Gate; destructive verbs (`delete_*`, `revoke_*`, `destroy_*`, `drop_*`, `purge_*`, `remove_*`) require approval. |
208+
| `filesystem` | Reads allowed; writes require approval; destructive verbs (`delete_*`, `purge_*`, `truncate_*`, `wipe_*`, `format_*`, `rm`, `rmdir_*`, `unlink_*`, `clean_*`) blocked. |
209+
| `shell` | All shell tool calls require approval. |
210+
211+
Customize via the `policy.rules[]` field in
212+
`~/.avp/mcp-proxy/config.json`. Built-in packs are starter templates, not
213+
exhaustive; review patterns for your specific downstream server.
214+
215+
## CLI Commands
216+
217+
| Command | Purpose |
218+
|---|---|
219+
| `init` | Create encrypted identity, config, and control grant. |
220+
| `doctor` | Validate local files and control grant. |
221+
| `run` | Run stdio passthrough, the proxy mode used by MCP clients. |
222+
| `reissue-grant` | Refresh the local control grant before expiry. |
223+
| `export-evidence <path>` | Export durable evidence bundle for offline verification. |
224+
| `verify <bundle.json>` | Verify a previously exported bundle. |
225+
| `events --vacuum` | Prune old terminal evidence records. |
226+
227+
See [Operations][ops] for full flag reference and headless/CI patterns.
228+
229+
## Evidence And Proof
230+
231+
Every approval-gated tool call writes a durable record to a local SQLite
232+
evidence store (`~/.avp/mcp-proxy/evidence.sqlite`, owner-only). Records are
233+
hash-chained, fsync'd on write, and reference signed AVP DecisionReceipt
234+
digests when Runtime Gate authorized the action.
235+
236+
Export an evidence bundle for offline verification:
237+
238+
```bash
239+
agentveil-mcp-proxy export-evidence ./bundle.json
240+
agentveil-mcp-proxy verify ./bundle.json --trusted-signer-did did:key:...
241+
```
242+
243+
The verifier validates chain integrity, receipt signature against pinned signer
244+
DIDs, schema, `audit_id` binding, `payload_hash` binding, risk class, and policy
245+
context hash. See [Operations: Evidence][ops-evidence].
246+
247+
## Headless Mode
248+
249+
For automation and CI, run without a browser approval UI. Either auto-deny every
250+
approval-required action, or load a bounded headless policy that pre-approves
251+
specific `(server, tool, risk_class, payload_hash)` tuples.
252+
253+
```bash
254+
agentveil-mcp-proxy run --headless --auto-deny
255+
agentveil-mcp-proxy run --headless --headless-policy ./headless.json
256+
```
257+
258+
See [Operations: Headless][ops-headless].
259+
260+
## Operations And Security
261+
262+
For full operational depth - passphrase handling, policy override semantics,
263+
multi-instance deployment, evidence vacuum, identity migration, and security
264+
trade-offs - see [`docs/MCP_PROXY_OPERATIONS.md`][ops].
265+
266+
## Relationship To AVP
267+
268+
`agentveil-mcp-proxy` is one integration adapter for Agent Veil Protocol. The
269+
core trust/control/evidence primitives - Runtime Gate, DecisionReceipt
270+
verification, controlled-action flow, identity, and audit chain - live in the
271+
[`agentveil`](../README.md) SDK. This package is the MCP-transport adapter for
272+
IDE clients; other adapters exist for direct SDK use, framework integrations
273+
(CrewAI, LangGraph, AutoGen, OpenAI), AWS Bedrock, and Microsoft AgentMesh.
274+
275+
See the top-level [README](../README.md) for the full integration matrix and
276+
the [API docs](https://agentveil.dev/docs) for endpoint-level detail.
277+
278+
## Roadmap
279+
280+
v0.1 ships with these documented limitations targeted for v0.1.1:
281+
282+
- **Backend protocol nonce/freshness:** local replay cache mitigates
283+
same-process replays within a 5-minute window; full protocol fix adds
284+
backend-issued nonce plus `issued_at` and `expires_at` to
285+
`decision_receipt/3`.
286+
- **Windows orphan process containment:** Linux and macOS handle downstream
287+
orphan cleanup correctly; Windows Job Object assignment has a narrow race
288+
window during `start()`. Run under a supervisor on Windows in production for
289+
now.
290+
- **OS keychain identity storage:** v0.1 uses passphrase-encrypted Argon2id
291+
identity files. v0.1.1+ adds opt-in macOS Keychain, Linux Secret Service, and
292+
Windows Credential Manager integration.
293+
294+
[ops]: ../docs/MCP_PROXY_OPERATIONS.md
295+
[ops-passphrase]: ../docs/MCP_PROXY_OPERATIONS.md#security-trade-offs-by-passphrase-source
296+
[ops-evidence]: ../docs/MCP_PROXY_OPERATIONS.md#local-evidence-storage
297+
[ops-headless]: ../docs/MCP_PROXY_OPERATIONS.md#headless-approval-mode

‎agentveil_mcp_proxy/__main__.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
"""Allow running as: python -m agentveil_mcp_proxy"""
2+
from agentveil_mcp_proxy.cli import main
3+
4+
if __name__ == "__main__":
5+
raise SystemExit(main())

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ include = ["agentveil*", "agentveil_mcp*", "mcp_server*"]
5151

5252
[tool.setuptools.package-data]
5353
agentveil_mcp = ["README.md"]
54+
agentveil_mcp_proxy = ["README.md"]
5455
mcp_server = ["README.md"]
5556

5657
[tool.pytest.ini_options]

0 commit comments

Comments
 (0)