Back to search
autonomy-gateway
MCP serverGitHub
MCP gateway that lets AI agents act on their own where actions are low risk and can be undone, asks where they can't, and stops at a budget you set. Reference implementation for MCP proposals on undo, cost and autonomy budgets.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/probita-ai--autonomy-gateway)HTML
<a href="/listings/probita-ai--autonomy-gateway"><img src="/api/listings/probita-ai--autonomy-gateway/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
bin/agw init bin/agw add-server NAME -- COMMAND ARGS... # any stdio MCP server, e.g. npx -y @modelcontextprotocol/server-filesystem ~/Docs bin/agw tools # what will happen with each tool bin/agw mcp-config # prints: claude mcp add autonomy-gateway -- …/bin/agw serve
Try it with no setup: `python3 examples/demo.py` (uses a throwaway home and a fake travel server).
Put Personal Context Server behind it:
pcs grant agw general --write propose bin/agw add-server pcs -- env PYTHONPATH=/path/to/personal-context-server python3 -m pcs.mcp_server --client agw
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 133 lines
- # Autonomy Gateway
- An MCP gateway that lets an AI agent act on its own where actions are low risk and can be undone, asks you
- where they can't, and stops when a budget you set runs out. It sits between your AI app and your existing MCP
- servers, so neither has to change.
- Reference implementation (v0.2) of the MCP Autonomy Extension draft, and of the two proposals in [`sep/`](sep/). Python 3.9+ standard library only.
- ```
- AI app (Claude Code, …) ──MCP──▶ autonomy gateway ──MCP──▶ your servers (unchanged)
- 1 contract check
- 2 budget check
- 3 approval (elicitation, or `agw approve`)
- 4 run, record outcome, offer undo
- ```
- ## What it decides
- Each tool's **contract** (risk, whether and how it can be undone, cost) comes from, in order: your override in
- `config.json`, the tool's `_meta["x-autonomy/contract"]`, the Tool Annotations IG's
- `io.modelcontextprotocol/action-metadata`, the core `readOnlyHint`/`destructiveHint`, or nothing. **Nothing
- counts as high risk and can't be undone.**
- | Risk | Can be undone | Undo window | Can't be undone |
- |---|---|---|---|
- | low | auto | auto | ask |
- | medium | auto | auto + notify | ask |
- | high | ask | ask | ask |
- | critical | deny | deny | deny |
- On top of that:
- - **Budget per goal**: calls, USD, minutes, and actions that can't be undone. The agent can set limits up to your
- `ceiling`, never past it. A call that would go over is not run; the agent gets a *paused* result and a
- checkpoint is saved.
- - **Undo**: if a tool says how to undo it (`undoArgumentsFrom`), the agent is handed the exact undo call.
- - **Learning**: every call is recorded. `autonomy_discover` ranks tools by match × past success. A failed undo
- raises the original tool's risk until you `agw reset` it.
- - **Bait-and-switch protection**: if a tool you've used or "always allowed" changes its description or
- contract, the gateway asks again.
- - **Kill switch**: `agw stop`.
- ## Quick start
- ```sh
- bin/agw init
- bin/agw add-server NAME -- COMMAND ARGS... # any stdio MCP server, e.g. npx -y @modelcontextprotocol/server-filesystem ~/Docs
- bin/agw tools # what will happen with each tool
- bin/agw mcp-config # prints: claude mcp add autonomy-gateway -- …/bin/agw serve
- ```
- Try it with no setup: `python3 examples/demo.py` (uses a throwaway home and a fake travel server).
- Put Personal Context Server behind it:
- ```sh
- pcs grant agw general --write propose
- bin/agw add-server pcs -- env PYTHONPATH=/path/to/personal-context-server python3 -m pcs.mcp_server --client agw
- ```
- ## Day to day
- | Task | Command |
- |---|---|
- | What is it doing? | `agw status`, `agw log` |
- | Approve a waiting call (apps without approval prompts) | `agw approvals`, `agw approve 3 [--always]`, `agw deny 3` |
- | Give a goal more room | `agw budget --usd 50 --calls 100` (only you can go past the ceiling) |
- | Always allow a tool / stop | `agw trust pcs__remember`, `agw untrust …` |
- | Clear a raised risk | `agw reset travel__book_train` |
- | Stop everything | `agw stop`, then `agw resume` |
- ## Tools and methods the agent sees
- | Name | What it does |
- |---|---|
- | `autonomy_discover(intent, maxRisk?, maxCostUsd?)` | ranked tools for a need, with risk, undo, cost, success rate, and whether calling will ask |
- | `autonomy_call(tool, arguments)` | call a discovered tool (useful with `"expose": "discover"`, which hides everything else) |
- | `autonomy_budget(goal?, limits?)` | name the goal, set limits within the ceiling, or see what's left |
- | `<server>__<tool>` | every allowed downstream tool, with the decision appended to its description |
- Extension-aware clients can use `autonomy/discover`, `autonomy/budget.set` and `autonomy/budget.get` directly, and
- read the `_meta` signals `x-autonomy/paused`, `x-autonomy/pendingApproval` and `x-autonomy/undo`.
- ## Config (`~/.agw/config.json`)
- ```json
- {
- "servers": {"travel": {"command": ["python3", "examples/travel_server.py"], "env": {}}},
- "expose": "all",
- "ceiling": {"calls": 200, "usd": 10.0, "minutes": 120, "irreversible": null},
- "contracts": {"pcs__remember": {"risk": "low", "reversible": "yes"}},
- "decisions": {"travel__send_email": "deny"},
- "approval_timeout_sec": 300
- }
- ```
- Re-read on every call, so changes apply immediately. `AGW_HOME` moves everything elsewhere.
- ## Limits of v0.2
- - stdio only; no HTTP transport yet.
- - The app's identity isn't verified; anything that can launch `agw serve` as you gets your policy.
- - Server-declared contracts are claims. Your overrides and observed failures correct them; nothing proves them.
- - Skill forge (agent-written tools) is not implemented; it's planned for v0.4.
- ## Layout
- ```
- agw/contracts.py contract sources, the decision table, fingerprints, undo calls
- agw/budget.py goals, ceiling, checks, checkpoints
- agw/discover.py intent search weighted by past success
- agw/gateway.py the MCP gateway
- agw/client.py stdio MCP client (downstream servers, tests, demo)
- agw/store.py SQLite state shared with the CLI
- agw/cli.py the agw command
- examples/ fake travel server and the demo
- sep/ the two proposals for the MCP project
- tests/ python3 -m unittest discover -s tests
- ```
- ## Related
- - [HATP](https://github.com/probita-ai/hatp), the Human-Agent Transaction Protocol. HATP makes a multi-step plan
- all-or-nothing, with a human approver as one of the voters. This gateway works one call at a time and decides
- whether a human is needed at all. The two fit together: a call the gateway would *ask* about can be sent to a
- HATP Human Gateway, and the gateway's undo windows play the same role as HATP's holds.
- - [Agent Work Layer](https://github.com/probita-ai/agent-work-layer) and
- [Agent Org Model](https://github.com/probita-ai/agent-org-model), from the same organization.
- ## License
- Apache-2.0, the license SEP-2133 requires for official MCP extensions, so this code and the proposals in
- `sep/` can move into an MCP repository without relicensing.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.