New to this? This guide goes from a fresh Claude install to Claude working through Aggrete, so a policy you set is enforced on every request. No prior MCP experience needed, about 15 minutes.
Two ways to get the idea in a couple of minutes.
A read-only demo on a sample company: what was checked, what was prevented, and why, in plain language. Nothing to install.
Open the consoleOne command, no config and no network. It asks four questions and shows an allow, a warning, and a refusal.
# Python 3.10+
pip install aggrete
aggrete --demoThis runs Aggrete on your own machine against bundled mock connectors, so you can watch it work end to end before wiring in your real systems.
Aggrete needs Python 3.10 or newer.
python3 --version # need 3.10 or newer
On a Mac the built-in python3 is often 3.9, which is too old. If so, install a newer one (brew install python@3.12) and use that to create the virtualenv below.
Clone the repo so you have a ready policy (coc.yaml), a proxy config, and mock HR, finance and ops connectors to try it against.
git clone https://github.com/aggrete/aggrete cd aggrete python3 -m venv .venv && .venv/bin/pip install -e .
Run the proxy once by hand. It launches the mock connectors and waits for a client. Press Ctrl-C to stop, then let Claude launch it in the next step.
.venv/bin/aggrete --config proxy.config.yaml
Pick how you use Claude. Both run Aggrete locally over stdio, so nothing leaves your machine. Use full paths.
claude mcp add aggrete -- \ "$PWD"/.venv/bin/aggrete \ --config "$PWD"/proxy.config.yaml
Then type /mcp in Claude Code to see the tools appear.
Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/), then quit and reopen Claude.
{
"mcpServers": {
"aggrete": {
"command": "/PATH/aggrete/.venv/bin/aggrete",
"args": ["--config",
"/PATH/aggrete/proxy.config.yaml"]
}
}
}Ask Claude to do something the sample policy forbids, like combining budget and personnel records to flag who might be let go. Aggrete refuses before anything is fetched, and hands Claude the reason instead of the data. Ordinary questions pass straight through.
Three things to change when you are ready to move past the mocks.
Edit coc.yaml by hand, or drop your handbook into the console and let it draft rules you review. Turn protection packs on and off in plain language.
Replace the mocks with a connector, Google Drive, Slack, GitHub and more, each fenced to a boundary and mapped to a policy domain.
See connectorsSome requests should not be refused, just signed off. Mark a rule action: approve and the call pauses before anything is fetched until the clause owner approves it, in the console, the terminal, or over the API.
Run Aggrete as a service with sign-in, so every teammate's Claude goes through the same policy. Same rules, one place.
Deploy optionsEverything on this page, plus the rule-type and config references, packaged as a skill. Your assistant reads it once and can then write and test coc.yaml rules, wire a connector, or explain a refusal from the audit log without you pasting docs.
Two commands in Claude Code. The skill triggers on Aggrete, coc.yaml, policy questions, and "govern what my assistant can reach".
# inside Claude Code
/plugin marketplace add aggrete/aggrete
/plugin install aggrete@aggreteA running Aggrete serves its own skill as MCP resources, so Cursor, Codex, or anything that speaks MCP can pull the guide straight from the server it is talking to.
# resources on every Aggrete server
skill://aggrete/SKILL.md
skill://aggrete/references/rule-types.md
skill://aggrete/references/config.mdThe two-file mental model, which rule type fits which clause, testing and linting, the four auth modes, deploy shapes, and how to read a hash-chained audit line. Plain Markdown you can read yourself.
Read SKILL.mdStart on a laptop, graduate to a shared service, make it the company default, or embed the enforcement in a gateway you already run.
The simplest path. Identity is advisory; good for trying rules against the mocks or your own connectors.
# .mcp.json in the project root
python -m aggrete.proxy
--config proxy.config.yamlOne streamable-HTTP service. Users are derived from the OAuth token; state in Redis for multiple replicas. Serves /metrics, /healthz and /readyz.
# requires auth: in config
--transport streamable-http
--host 0.0.0.0 --port 8080Ship a managed MCP config by MDM and fence connectors to the proxy host, so assistants can only talk to Aggrete.
# helm
helm install aggrete
deploy/helm/aggreteAlready run a gateway? Add just the enforcement via the before/after hook or the ASGI middleware.
# aggrete/plugin.py
from aggrete.plugin import
PolicyHook, AggreteMiddlewareThe idea in depth: pre-call refusals, the rule types, and where the proxy sits.
Put a real system behind the proxy, folder by folder, channel by channel.
Sixteen runnable checks mapped onto OWASP, CoSAI and AIUC-1, plus a black-box suite you can point at any gateway.
Install the plugin, or let any MCP client read the guide from the proxy itself.
Concepts, the demo, and the full reference on GitHub.
If a step did not work or a clause is hard to model, open an issue. It is the fastest way to get help, and it makes the guide better for the next person.