Skip to content
Back to search

autonomy-gateway

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/probita-ai--autonomy-gateway/badge.svg)](/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
  1. # Autonomy Gateway
  2. An MCP gateway that lets an AI agent act on its own where actions are low risk and can be undone, asks you
  3. where they can't, and stops when a budget you set runs out. It sits between your AI app and your existing MCP
  4. servers, so neither has to change.
  5. Reference implementation (v0.2) of the MCP Autonomy Extension draft, and of the two proposals in [`sep/`](sep/). Python 3.9+ standard library only.
  6. ```
  7. AI app (Claude Code, …) ──MCP──▶ autonomy gateway ──MCP──▶ your servers (unchanged)
  8. 1 contract check
  9. 2 budget check
  10. 3 approval (elicitation, or `agw approve`)
  11. 4 run, record outcome, offer undo
  12. ```
  13. ## What it decides
  14. Each tool's **contract** (risk, whether and how it can be undone, cost) comes from, in order: your override in
  15. `config.json`, the tool's `_meta["x-autonomy/contract"]`, the Tool Annotations IG's
  16. `io.modelcontextprotocol/action-metadata`, the core `readOnlyHint`/`destructiveHint`, or nothing. **Nothing
  17. counts as high risk and can't be undone.**
  18. | Risk | Can be undone | Undo window | Can't be undone |
  19. |---|---|---|---|
  20. | low | auto | auto | ask |
  21. | medium | auto | auto + notify | ask |
  22. | high | ask | ask | ask |
  23. | critical | deny | deny | deny |
  24. On top of that:
  25. - **Budget per goal**: calls, USD, minutes, and actions that can't be undone. The agent can set limits up to your
  26. `ceiling`, never past it. A call that would go over is not run; the agent gets a *paused* result and a
  27. checkpoint is saved.
  28. - **Undo**: if a tool says how to undo it (`undoArgumentsFrom`), the agent is handed the exact undo call.
  29. - **Learning**: every call is recorded. `autonomy_discover` ranks tools by match × past success. A failed undo
  30. raises the original tool's risk until you `agw reset` it.
  31. - **Bait-and-switch protection**: if a tool you've used or "always allowed" changes its description or
  32. contract, the gateway asks again.
  33. - **Kill switch**: `agw stop`.
  34. ## Quick start
  35. ```sh
  36. bin/agw init
  37. bin/agw add-server NAME -- COMMAND ARGS... # any stdio MCP server, e.g. npx -y @modelcontextprotocol/server-filesystem ~/Docs
  38. bin/agw tools # what will happen with each tool
  39. bin/agw mcp-config # prints: claude mcp add autonomy-gateway -- …/bin/agw serve
  40. ```
  41. Try it with no setup: `python3 examples/demo.py` (uses a throwaway home and a fake travel server).
  42. Put Personal Context Server behind it:
  43. ```sh
  44. pcs grant agw general --write propose
  45. bin/agw add-server pcs -- env PYTHONPATH=/path/to/personal-context-server python3 -m pcs.mcp_server --client agw
  46. ```
  47. ## Day to day
  48. | Task | Command |
  49. |---|---|
  50. | What is it doing? | `agw status`, `agw log` |
  51. | Approve a waiting call (apps without approval prompts) | `agw approvals`, `agw approve 3 [--always]`, `agw deny 3` |
  52. | Give a goal more room | `agw budget --usd 50 --calls 100` (only you can go past the ceiling) |
  53. | Always allow a tool / stop | `agw trust pcs__remember`, `agw untrust …` |
  54. | Clear a raised risk | `agw reset travel__book_train` |
  55. | Stop everything | `agw stop`, then `agw resume` |
  56. ## Tools and methods the agent sees
  57. | Name | What it does |
  58. |---|---|
  59. | `autonomy_discover(intent, maxRisk?, maxCostUsd?)` | ranked tools for a need, with risk, undo, cost, success rate, and whether calling will ask |
  60. | `autonomy_call(tool, arguments)` | call a discovered tool (useful with `"expose": "discover"`, which hides everything else) |
  61. | `autonomy_budget(goal?, limits?)` | name the goal, set limits within the ceiling, or see what's left |
  62. | `<server>__<tool>` | every allowed downstream tool, with the decision appended to its description |
  63. Extension-aware clients can use `autonomy/discover`, `autonomy/budget.set` and `autonomy/budget.get` directly, and
  64. read the `_meta` signals `x-autonomy/paused`, `x-autonomy/pendingApproval` and `x-autonomy/undo`.
  65. ## Config (`~/.agw/config.json`)
  66. ```json
  67. {
  68. "servers": {"travel": {"command": ["python3", "examples/travel_server.py"], "env": {}}},
  69. "expose": "all",
  70. "ceiling": {"calls": 200, "usd": 10.0, "minutes": 120, "irreversible": null},
  71. "contracts": {"pcs__remember": {"risk": "low", "reversible": "yes"}},
  72. "decisions": {"travel__send_email": "deny"},
  73. "approval_timeout_sec": 300
  74. }
  75. ```
  76. Re-read on every call, so changes apply immediately. `AGW_HOME` moves everything elsewhere.
  77. ## Limits of v0.2
  78. - stdio only; no HTTP transport yet.
  79. - The app's identity isn't verified; anything that can launch `agw serve` as you gets your policy.
  80. - Server-declared contracts are claims. Your overrides and observed failures correct them; nothing proves them.
  81. - Skill forge (agent-written tools) is not implemented; it's planned for v0.4.
  82. ## Layout
  83. ```
  84. agw/contracts.py contract sources, the decision table, fingerprints, undo calls
  85. agw/budget.py goals, ceiling, checks, checkpoints
  86. agw/discover.py intent search weighted by past success
  87. agw/gateway.py the MCP gateway
  88. agw/client.py stdio MCP client (downstream servers, tests, demo)
  89. agw/store.py SQLite state shared with the CLI
  90. agw/cli.py the agw command
  91. examples/ fake travel server and the demo
  92. sep/ the two proposals for the MCP project
  93. tests/ python3 -m unittest discover -s tests
  94. ```
  95. ## Related
  96. - [HATP](https://github.com/probita-ai/hatp), the Human-Agent Transaction Protocol. HATP makes a multi-step plan
  97. all-or-nothing, with a human approver as one of the voters. This gateway works one call at a time and decides
  98. whether a human is needed at all. The two fit together: a call the gateway would *ask* about can be sent to a
  99. HATP Human Gateway, and the gateway's undo windows play the same role as HATP's holds.
  100. - [Agent Work Layer](https://github.com/probita-ai/agent-work-layer) and
  101. [Agent Org Model](https://github.com/probita-ai/agent-org-model), from the same organization.
  102. ## License
  103. Apache-2.0, the license SEP-2133 requires for official MCP extensions, so this code and the proposals in
  104. `sep/` can move into an MCP repository without relicensing.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.