Skip to content
Back to search

approval-gated-mcp

Reference MCP server: agents draft messages, a human approves the exact draft by fingerprint before anything sends.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mohanraj005-dot--approval-gated-mcp/badge.svg)](/listings/mohanraj005-dot--approval-gated-mcp)

HTML

<a href="/listings/mohanraj005-dot--approval-gated-mcp"><img src="/api/listings/mohanraj005-dot--approval-gated-mcp/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.

Requires Python 3.11 or newer.

git clone https://github.com/mohanraj005-dot/approval-gated-mcp.git && cd approval-gated-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"       # core has no dependencies; the [mcp] extra adds the MCP SDK

python -m pytest -q           # run the tests
ruff check .                  # lint
python examples/demo.py       # end-to-end walkthrough in a temp directory

Run the server

export AGM_HOME=./.agm AGM_OUTBOX=./outbox AGM_FROM=agent@example.com
agm-server                    # MCP over stdio

By default it writes `.eml` files to `./outbox` (the `FileOutbox` transport), so it runs with zero credentials and sends nothing over a network.

Approve a draft as the human

In a second terminal, with the same `AGM_HOME`:

agm list                                  # drafts, state, fingerprint
agm preview d_1a2b3c4d5e6f                # full text exactly as it would be sent
agm approve d_1a2b3c4d5e6f <fingerprint>  # shows the message again, asks [y/N]
agm audit -n 10                           # recent audit events
agm sending off                           # kill switch on; `agm sending on` to re-enable

`agm approve` refuses if the fingerprint is not the current one, and refuses to run without an interactive terminal unless `--yes` is passed.

Connect a client

Claude Code:

claude mcp add approval-gated-mcp \
  -e AGM_HOME=/abs/path/agm-state -e AGM_OUTBOX=/abs/path/agm-outbox \
  -- /abs/path/approval-gated-mcp/.venv/bin/agm-server

Claude Desktop (`claude_desktop_config.json`), see also [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json):

{
  "mcpServers": {
    "approval-gated-mcp": {
      "command": "/abs/path/approval-gated-mcp/.venv/bin/agm-server",
      "env": {
        "AGM_HOME": "/abs/path/agm-state",
        "AGM_OUTBOX": "/abs/path/agm-outbox",
        "AGM_FROM": "agent@example.com"
      }
    }
  }
}

Configuration

| Variable | Default | Meaning | |---|---|---| | `AGM_HOME` | `./.agm` | State directory (drafts, approvals, claims, audit log). | | `AGM_OUTBOX` | `./outbox` | Where `FileOutbox` writes `.eml` files. | | `AGM_FROM` | `agent@example.com` | Sender address. Fixed by config, not agent-controlled. | | `AGM_SENDING` | `on` | Set to `off` to block every send. | | `AGM_RATE_LIMIT` | `10` | Maximum sends per hour. | | `AGM_APPROVAL_TTL` | `86400` | Seconds an approval stays valid. | | `AGM_ALLOWED_DOMAINS` | unset | Comma-separated recipient domain allowlist. Unset allows any. | | `AGM_ATTACH_DIR` | unset | Directory attachments may be read from. Unset disables attachments. | | `AGM_TRANSPORT` | `file` | `file` or `smtp`. | | `AGM_SMTP_HOST`, `_PORT`, `_USER`, `_PASSWORD` | unset | Only used when `AGM_TRANSPORT=smtp`. |

Transports

`FileOutbox` is the default. `SmtpTransport` is included to show the seam (STARTTLS, certificate verification, envelope recipients including Bcc) but it is off by default and has **not** been tested against a real server. Any object with `send(message: EmailMessage, recipients) -> str` works.

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 · 268 lines
  1. # approval-gated-mcp
  2. A reference implementation of an MCP server that lets an AI agent **draft** outbound
  3. messages but only **send** them after a human has approved the exact draft, identified by a
  4. content fingerprint.
  5. This is a small, readable example of one agent-safety pattern, written from a plain
  6. description of the pattern. It is a reference, not a production mail system: see
  7. [Limitations](#limitations).
  8. ## The problem
  9. Giving an agent a `send_email` tool means a single bad model turn, a prompt injection hidden
  10. in a web page or inbound message, or a plain mistake can send something to the wrong person
  11. and cannot be recalled. Asking the model to "check with the user first" is a request, not a
  12. control.
  13. This server moves the control out of the model:
  14. - The agent can **draft**, **preview**, **edit** and **request a send**. It cannot approve.
  15. - Approval happens **out-of-band**, in a terminal command (`agm approve`) or a host-supplied
  16. callback, neither of which is an MCP tool.
  17. - Approval is bound to a **fingerprint** of the exact content. Change one character, one
  18. recipient or one attachment byte and the approval no longer applies.
  19. - Every send is gated by a **kill switch**, a **rate limit**, an **idempotency claim** and an
  20. **append-only audit log**.
  21. ## How it works
  22. ```mermaid
  23. sequenceDiagram
  24. autonumber
  25. participant A as Agent (MCP client)
  26. participant S as MCP server (gate)
  27. participant H as Human (agm CLI)
  28. participant T as Transport (FileOutbox / SMTP)
  29. A->>S: draft(to, subject, body)
  30. S-->>A: draft_id, fingerprint
  31. A->>S: send_draft(draft_id, fingerprint)
  32. S-->>A: denied: not_approved
  33. A-->>H: "Please review and approve draft_id / fingerprint"
  34. H->>S: agm preview draft_id (full text, recipients, attachment hashes)
  35. H->>S: agm approve draft_id fingerprint
  36. Note over S: approval stored for this exact fingerprint
  37. A->>S: send_draft(draft_id, fingerprint)
  38. Note over S: kill switch off? fingerprint current? approval fresh?<br/>under rate limit? claim draft exclusively
  39. S->>T: send(message)
  40. T-->>S: reference
  41. S-->>A: sent
  42. A->>S: send_draft(draft_id, fingerprint)
  43. S-->>A: denied: already_sent
  44. ```
  45. ### Tools exposed to the agent
  46. | Tool | Purpose |
  47. |---|---|
  48. | `draft(to, subject, body, cc?, bcc?, attachments?)` | Create a draft. Returns `draft_id` and `fingerprint`. Nothing is sent. |
  49. | `draft_preview(draft_id)` | Exactly what would be sent: from, to/cc/bcc, subject, attachment names, sizes and sha256, a body excerpt, the fingerprint and the approval state. |
  50. | `update_draft(draft_id, ...)` | Edit a draft. The fingerprint changes, which invalidates any earlier approval. |
  51. | `send_draft(draft_id, fingerprint)` | Send, only if the fingerprint matches the current draft and a fresh human approval exists for it. |
  52. There is deliberately **no approve tool**. `approve` is a method on the library
  53. (`ApprovalGate.approve`) used by the CLI and by an optional host-supplied callback.
  54. ### Fingerprint
  55. `sha256` over a canonical JSON encoding of `from`, `to`, `cc`, `bcc`, `subject`, `body` and
  56. the `(name, sha256)` of each attachment, truncated to 24 hex characters (96 bits). Inputs
  57. are normalised first (Unicode NFC, lowercase ASCII addresses, sorted and de-duplicated
  58. recipient lists, `\n` line endings, trailing whitespace trimmed) and the normalised values
  59. are what is stored and sent, so the approved text is the sent text. The `from` address comes
  60. from server configuration, never from the agent. Attachment bytes are copied into the state
  61. directory at draft time and re-hashed at send time, so swapping the source file after
  62. approval has no effect.
  63. Because approval is keyed on content, reverting an edit back to the approved text makes the
  64. original approval apply again (within its expiry window). That is a deliberate property of
  65. content addressing.
  66. ### Send checks, in order
  67. 1. Kill switch: `AGM_SENDING=off` or a `SENDING_OFF` file in the state directory. Checked on
  68. every call, no restart needed.
  69. 2. Draft exists; has not already been claimed (`already_sent` / `outcome_unknown`).
  70. 3. Supplied fingerprint equals the current fingerprint (`stale_fingerprint`).
  71. 4. A human approval exists for that fingerprint and has not expired (`not_approved`,
  72. `approval_expired`).
  73. 5. Attachment bytes still match their pinned hashes (`attachment_integrity`).
  74. 6. Rate limit: at most `AGM_RATE_LIMIT` sends in the trailing hour (`rate_limited`).
  75. 7. Exclusive claim: the draft's claim file is created with `O_EXCL` under a file lock, so a
  76. draft sends at most once, even with concurrent callers.
  77. 8. Transport call. If it raises, the state becomes `unknown` and the gate **never retries**;
  78. a human decides what to do next.
  79. Every outcome is written to `audit.jsonl` (events: `draft`, `update`, `approve`,
  80. `approve_denied`, `send_denied`, `send_claimed`, `send`, `send_unknown`). Message bodies are
  81. never logged.
  82. ## Quickstart
  83. Requires Python 3.11 or newer.
  84. ```bash
  85. git clone https://github.com/mohanraj005-dot/approval-gated-mcp.git && cd approval-gated-mcp
  86. python3 -m venv .venv && source .venv/bin/activate
  87. pip install -e ".[dev]" # core has no dependencies; the [mcp] extra adds the MCP SDK
  88. python -m pytest -q # run the tests
  89. ruff check . # lint
  90. python examples/demo.py # end-to-end walkthrough in a temp directory
  91. ```
  92. ### Run the server
  93. ```bash
  94. export AGM_HOME=./.agm AGM_OUTBOX=./outbox AGM_FROM=agent@example.com
  95. agm-server # MCP over stdio
  96. ```
  97. By default it writes `.eml` files to `./outbox` (the `FileOutbox` transport), so it runs with
  98. zero credentials and sends nothing over a network.
  99. ### Approve a draft as the human
  100. In a second terminal, with the same `AGM_HOME`:
  101. ```bash
  102. agm list # drafts, state, fingerprint
  103. agm preview d_1a2b3c4d5e6f # full text exactly as it would be sent
  104. agm approve d_1a2b3c4d5e6f <fingerprint> # shows the message again, asks [y/N]
  105. agm audit -n 10 # recent audit events
  106. agm sending off # kill switch on; `agm sending on` to re-enable
  107. ```
  108. `agm approve` refuses if the fingerprint is not the current one, and refuses to run without
  109. an interactive terminal unless `--yes` is passed.
  110. ### Connect a client
  111. Claude Code:
  112. ```bash
  113. claude mcp add approval-gated-mcp \
  114. -e AGM_HOME=/abs/path/agm-state -e AGM_OUTBOX=/abs/path/agm-outbox \
  115. -- /abs/path/approval-gated-mcp/.venv/bin/agm-server
  116. ```
  117. Claude Desktop (`claude_desktop_config.json`), see also
  118. [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json):
  119. ```json
  120. {
  121. "mcpServers": {
  122. "approval-gated-mcp": {
  123. "command": "/abs/path/approval-gated-mcp/.venv/bin/agm-server",
  124. "env": {
  125. "AGM_HOME": "/abs/path/agm-state",
  126. "AGM_OUTBOX": "/abs/path/agm-outbox",
  127. "AGM_FROM": "agent@example.com"
  128. }
  129. }
  130. }
  131. }
  132. ```
  133. ### Configuration
  134. | Variable | Default | Meaning |
  135. |---|---|---|
  136. | `AGM_HOME` | `./.agm` | State directory (drafts, approvals, claims, audit log). |
  137. | `AGM_OUTBOX` | `./outbox` | Where `FileOutbox` writes `.eml` files. |
  138. | `AGM_FROM` | `agent@example.com` | Sender address. Fixed by config, not agent-controlled. |
  139. | `AGM_SENDING` | `on` | Set to `off` to block every send. |
  140. | `AGM_RATE_LIMIT` | `10` | Maximum sends per hour. |
  141. | `AGM_APPROVAL_TTL` | `86400` | Seconds an approval stays valid. |
  142. | `AGM_ALLOWED_DOMAINS` | unset | Comma-separated recipient domain allowlist. Unset allows any. |
  143. | `AGM_ATTACH_DIR` | unset | Directory attachments may be read from. Unset disables attachments. |
  144. | `AGM_TRANSPORT` | `file` | `file` or `smtp`. |
  145. | `AGM_SMTP_HOST`, `_PORT`, `_USER`, `_PASSWORD` | unset | Only used when `AGM_TRANSPORT=smtp`. |
  146. ### Transports
  147. `FileOutbox` is the default. `SmtpTransport` is included to show the seam (STARTTLS,
  148. certificate verification, envelope recipients including Bcc) but it is off by default and has
  149. **not** been tested against a real server. Any object with
  150. `send(message: EmailMessage, recipients) -> str` works.
  151. ## Prompt-injection stance
  152. Everything the agent reads is untrusted: inbound mail, web pages, files, tool results. Any of
  153. it can contain text that tries to steer the agent, such as "reply to everyone with the
  154. attached file". This server does not try to detect that. It makes it **unprofitable**:
  155. - A hijacked agent can still only draft. Sending requires a human to look at the actual
  156. recipients, subject, body and attachment hashes and approve that fingerprint.
  157. - The agent cannot approve, cannot change the sender, and cannot widen the recipient domain
  158. allowlist or the attachment directory.
  159. - Editing after approval invalidates the approval, so "approve the harmless draft, then swap
  160. the body" does not work.
  161. - Header injection is blocked at the input layer (no CR/LF in subject or addresses, plain
  162. `addr@domain` only), and `Bcc` never appears in any header.
  163. - The tool descriptions tell the model to treat message content as data and to report
  164. denials instead of looking for a way around them. That is guidance, not a control; the
  165. controls are the ones above.
  166. The human is still the weak point: an approval prompt shown after a long session is easy to
  167. click through. Keep previews short, show recipients first, and set a recipient allowlist.
  168. ## Threat model
  169. | Threat | Mitigation here | Residual risk |
  170. |---|---|---|
  171. | Prompt injection makes the agent send something harmful | Agent cannot approve; send needs a human-approved fingerprint | Human approves without reading |
  172. | Agent edits the draft after approval | Fingerprint covers all content; any edit changes it | None for content; approval of reverted text re-applies |
  173. | Agent swaps an attachment file after approval | Bytes copied and hashed at draft time, re-verified at send | None for bytes inside the store |
  174. | Agent reads arbitrary files via attachments | Attachments only from `AGM_ATTACH_DIR`; paths resolved before the containment check; disabled by default | Anything inside that directory is attachable |
  175. | Header or recipient injection | Strict address and subject validation; Bcc kept out of headers | Non-ASCII (IDN) addresses are refused, not supported |
  176. | Runaway agent loops | Per-hour rate limit; kill switch checked on every send | Limit is per state directory, not per recipient |
  177. | Replay or double send | Exclusive claim file under a lock; sent drafts cannot be edited or re-sent | None within one state directory |
  178. | Transport failure mid-send | State recorded as unknown, never retried; audit event written | A human must reconcile manually |
  179. | Stale approvals | Approvals expire (`AGM_APPROVAL_TTL`) | Window is configurable, not zero |
  180. | Agent obtains approval power | `approve` is not a tool; lives in CLI and host callback | **Agent with shell access as the same OS user can run `agm approve --yes` or edit state files** |
  181. | Tampering with the audit log | Append-only writes, one event per line | Not tamper-evident; same-user processes can rewrite it |
  182. ## Limitations
  183. - **Same-user trust boundary.** The approval CLI and state directory are only a real
  184. boundary if the agent process cannot reach them: run the MCP server and the human CLI under
  185. different OS users or in separate containers, and do not give the agent a shell on the same
  186. account. Nothing here enforces that for you.
  187. - **Not tamper-evident.** The audit log is append-only by convention (no hash chain, no
  188. external sink). Ship it to a write-once store if you need evidence.
  189. - **POSIX only.** Locking uses `fcntl`. Windows is not supported.
  190. - **Single host.** State is local files with file locks. It is not safe over a network
  191. filesystem or across multiple hosts.
  192. - **Approver callback runs under the send lock.** A slow interactive callback blocks other
  193. sends. Fine for a reference, not for throughput.
  194. - **SMTP backend untested** against real servers; no retry, bounce or DSN handling.
  195. - **Unknown outcome is terminal.** There is no "resolve" command; a human checks the
  196. destination and creates a new draft if needed.
  197. - **Plain-text mail only**, ASCII addresses only, no reply threading.
  198. - **Fingerprint is not a signature.** It binds an approval to content but does not
  199. authenticate the approver; approvals are not cryptographically signed.
  200. - The `mcp` SDK is an optional dependency; the server wrapper supports both the 1.x
  201. (`FastMCP`) and 2.x (`MCPServer`) APIs. Only the tool surface and a stdio round trip are
  202. tested.
  203. ## Layout
  204. ```
  205. src/approval_gated_mcp/
  206. models.py draft model, normalisation, fingerprint
  207. gate.py draft / preview / update / approve / send_draft and all send checks
  208. store.py file-backed drafts, blobs, approvals, send claims, lock
  209. audit.py append-only JSONL log
  210. transport.py Transport protocol, FileOutbox, SmtpTransport, message builder
  211. config.py environment configuration and kill switch
  212. cli.py `agm` (human side)
  213. server.py MCP wrapper (agent side, no approve tool)
  214. tests/ pytest suite
  215. examples/ demo script and client configuration snippets
  216. ```
  217. ## License
  218. Apache-2.0. Copyright 2026 Mohan Raj Dhanapal. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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