A few weeks ago I gave an AI agent access to my machine through MCP. It read files, opened PRs, queried a database. It was great — until I looked at what it could have done if a tool description had been poisoned, or a prompt injection had slipped through.
The answer was: anything. ~/.ssh/id_rsa
. DROP TABLE users
. rm -rf /
. The agent had sudo, and nobody had voted for that.
So I built ** AgentPerms** — a CLI that gives MCP agents least-privilege permissions the same way you'd lock down any other process: figure out the minimum it actually needs, pin it, prove it, and enforce it.
pip install agentperms
MCP (the Model Context Protocol) is quietly becoming the USB-C of AI tooling. Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI — they all speak it. Which is wonderful, and also means your agent is one config file away from your filesystem, your repos, your inbox, and prod.
The existing tools each do part of the job:
Neither closes the loop. What I wanted was the boring, proven security workflow we already use for everything else: observe real behavior → derive least privilege → enforce it → keep it honest in CI.
That's the whole thesis of AgentPerms, as a pipeline:
record → infer → lock → replay → enforce
AgentPerms ships with a deliberately over-privileged demo MCP server, so you can watch a real policy decision without wiring anything up:
agentperms scan --path examples/vulnerable-mcp-demo
agentperms replay --policy examples/policies/example.mcp.policy.yaml
Output:
8/8 attacks blocked.
SSH-key exfiltration, .env
reads, rm -rf /
, unapproved email, force-push, repo deletion, destructive SQL — every one denied or routed to human approval before it would ever reach a server.
Here's the part I'm proud of. AgentPerms doesn't ask your agent to cooperate, and it doesn't patch the client. It rewrites the MCP client's config so every server launches through a transparent stdio proxy:
Agent → AgentPerms proxy → MCP server
│
├─ record: log every tools/call, then forward
└─ enforce: allow / deny / require-approval before forwarding
The proxy spawns the real server as a subprocess and pumps newline-delimited JSON-RPC both ways. It intercepts tools/call
requests and captures tools/list
responses. That's it. The agent has no idea it's there.
A server entry goes from this:
{ "command": "python3", "args": ["server.py"] }
to this (original command preserved after --
, with a .agentperms.bak
so you can roll back):
{
"command": "/usr/bin/python3",
"args": ["-m", "agentperms", "_proxy",
"--mode", "enforce", "--server", "demo",
"--policy", "/abs/path/mcp.policy.yaml",
"--", "python3", "server.py"]
}
In record mode it logs and forwards. In enforce mode it evaluates first and, on a DENY, returns a synthetic JSON-RPC error to the client without forwarding. Denied calls never touch the server.
You don't write the policy. You run your agent normally for a while with recording on:
agentperms record --client cursor
agentperms infer # traces -> mcp.policy.yaml
infer
is the killer command. It reads the traces and emits the minimum policy that still lets the agent do what it actually did:
allowed_tools
allowed_paths
denied_tools
/ human-approvalThe result reads like a security review wrote it for you:
Your agent only used read-only GitHub calls and local./src
access. It does not need shell, home directory, secrets, Gmail send, or database write access.
Whatever you do, there must be exactly one place that says allow/deny/approve — otherwise your offline tests and your live enforcement drift apart and you're testing a lie.
In AgentPerms that's a single evaluate(policy, server, tool, args)
function, called by both the live proxy and offline replay
. First-match-wins:
denied_tools
→ denied_paths
/ denied_patterns
→ allowed_tools
set and tool not in it → allowed_paths
set and a path falls outside it → An empty policy allows everything. The moment any server is constrained, unknown servers default-deny. What you test in replay
is byte-for-byte what runs in production, because it's the same code path.
The policy itself stays small and reviewable:
version: 1
servers:
github:
allowed_tools: [list_repos, read_file, create_issue]
denied_tools: [delete_repo, write_secret, force_push]
filesystem:
allowed_paths: [./src, ./docs]
denied_paths: [~/.ssh, ~/.env, /etc]
denied_patterns: ["*.pem", "*.key"]
approvals:
require_human_approval: [gmail.send_email, github.merge_pr, shell.exec]
redaction: { secrets: true, emails: true, api_keys: true }
There's a sneaky MCP attack class where a server silently changes a tool's description or schema after you've trusted it — the model re-reads it and gets quietly re-instructed. So AgentPerms also locks tool identity:
agentperms lock # hash every tool's name/description/schema
agentperms lock --check # fail if any of them changed
Drop lock --check
in CI and a poisoned tool fails the build instead of your users.
agentperms init # scaffolds .github/workflows/agentperms.yml
On every push/PR it runs:
agentperms scan --path . # surface risky configs
agentperms lock --check # fail on tool poisoning
agentperms replay # fail if the policy stops blocking attacks
Commit mcp.policy.yaml
and mcp.lock
, and your agent's permissions become a reviewable, version-controlled, enforceable artifact — like any other part of your security posture.
I'd rather be honest than oversell:
pip install agentperms
agentperms scan --path examples/vulnerable-mcp-demo
agentperms replay --policy examples/policies/example.mcp.policy.yaml
If you're running agents with real access to real systems, I'd genuinely love your feedback — especially on the policy model and what attack shapes you'd want in the replay pack. Issues and PRs welcome.
Your agent doesn't need sudo. Let's take it away.