approval-gate-mcp

An MCP server that puts a human approval gate in front of a long-running autonomous process, plus the operational tools you need to actually live with one: status, logs, restart, hot-reload parameters, and a summary of what it has done.

Built with FastMCP. Works with any MCP client.

The problem

A process that acts on its own is useful right up until one of its actions is consequential. The usual answers are both bad. Turn it off, and you lose everything it was doing well. Let it run, and you find out afterwards.

The gate is a third option. The process keeps running unattended, but when it wants to take an action you have marked as consequential, it writes a proposal and moves on instead of acting. You review proposals whenever you get to them, in whatever MCP client you already have open, and approve or reject. The process picks up your decision on its next cycle.

Neither side blocks the other. There is no service in between. The contract is two JSON files.

  process                            you
     |                                |
     |-- writes proposal ----> pending.json
     |                                |
     |                          list_pending_approvals
     |                          approve(0) / reject(1)
     |                                |
     |<-- reads on next cycle -- approved.json
     |
     |-- acts, appends to records.json

Tools

Approval gate

Tool	What it does
list_pending_approvals	Every proposal waiting on a decision, with all of its fields
approve(index)	Move one proposal to the approved file
reject(index)	Discard one proposal

Process control

Tool	What it does
process_status	Running or not, PID, uptime, CPU, memory, disk, last log line
process_logs(lines)	Tail the log file
restart_process	Restart via your start script, detached so it survives the SSH session
run_command(cmd)	Escape hatch for one-off checks

Records

Tool	What it does
record_summary(n)	Totals, resolved versus open, breakdown by type, recent entries
record_dashboard	Wider table view plus currently open records and their exposure

Parameters — registered only if PARAMS_SCHEMA points at your manifest

Tool	What it does
list_params	What this deployment declares tunable, and what is overridden right now
set_param(name, value)	Write one override, validated against your manifest
clear_param(name)	Remove one override, or all of them

Chain — registered only if EVM_RPC_URL, WALLET_ADDRESS, and TOKEN_CONTRACT are all set

Tool	What it does
wallet_balance	Read-only ERC-20 and native balance for a watch address. Nothing is signed

Install

git clone https://github.com/WillyV347/approval-gate-mcp
cd approval-gate-mcp
pip install -r requirements.txt
cp .env.example .env      # then edit it

Try it in the inspector before wiring it into a client:

fastmcp dev server.py

Then register it. For a client that reads a JSON config:

{
  "mcpServers": {
    "approval-gate": {
      "command": "python3",
      "args": ["/absolute/path/to/approval-gate-mcp/server.py"],
      "env": {
        "VPS_HOST": "your.host.or.ip",
        "VPS_USER": "your-ssh-user",
        "PROCESS_DIR": "/srv/my-process",
        "PROCESS_MATCH": "my_process.py",
        "PARAMS_SCHEMA": "/absolute/path/to/params.schema.json"
      }
    }
  }
}

There are no default values for VPS_HOST, VPS_USER, or PROCESS_DIR. The server exits with a clear message if they are missing. A monitoring tool that silently falls back to some host baked in by its author is a bug, so this one refuses to guess.

Authentication is your existing SSH setup. The server shells out to the system ssh binary, so agents, hardware keys, and password managers that expose an agent all work unchanged. It never reads a private key itself.

The contract your process implements

You need three things on the process side. None of them require a library.

1. Records. Append to a JSON array. Four keys are interpreted if present, and everything else is carried through untouched:

[
  {
    "id": "job-1041",
    "record_type": "reindex",
    "resolved": true,
    "outcome": "win",
    "cost": 4.25,
    "result": 11.80,
    "label": "nightly reindex, shard 3"
  }
]

2. Proposals. When running in approval mode, write here instead of acting:

{
  "proposals": [
    {
      "id": "job-1042",
      "label": "reindex shard 7",
      "action": "reindex",
      "cost": 6.00,
      "created_at": "2026-08-18T22:14:07Z"
    }
  ]
}

Every field you include is displayed. The server does not have a schema for proposals and does not want one.

3. Poll the approved file. On each cycle, read approved.json, act on what is there, and clear it. Roughly:

approved = read_json(APPROVED_FILE) or {"proposals": []}
for proposal in approved["proposals"]:
    execute(proposal)
write_json(APPROVED_FILE, {"proposals": []})

Ordering is deliberate on the server side. A decision removes the proposal from pending.json before writing to approved.json, so the failure mode of a half-completed decision is a dropped proposal, never a duplicated action.

Parameters, and why there are none in this repo

Hot-reload is only useful if the server knows what is tunable, and hardcoding one deployment's parameters into a shared tool makes it single-purpose. So you declare yours in a manifest and point PARAMS_SCHEMA at it:

{
  "poll_interval_seconds": { "type": "int",  "description": "Seconds between work cycles" },
  "max_concurrent_jobs":   { "type": "int",  "description": "Jobs in flight at once" },
  "dry_run":               { "type": "bool", "description": "Plan work but do not execute" },
  "approval_mode":         { "type": "bool", "description": "Queue proposals instead of acting" }
}

Supported types are int, float, bool, str, dict, and list. set_param coerces and validates against this and rejects anything that will not convert. Without a manifest the parameter tools are simply not registered, which is better than exposing a write path with nothing to check it against.

params.schema.json is gitignored, because your tuning is yours. params.schema.example.json ships as a starting point.

Have your process read the override file at startup, and on each cycle if you want changes to land without a restart:

overrides = read_json(PARAMS_FILE) or {}
poll_interval = overrides.get("poll_interval_seconds", POLL_INTERVAL_DEFAULT)

Example session

> is it running?

  Process RUNNING

  PID:      31882
  Uptime:   14h 22m (51720s)
  CPU:      0.6%
  Memory:   84.3 MB
  Disk:     212M

  Last log: 2026-08-18 22:03:11 cycle complete, 2 proposals queued

> anything waiting on me?

  2 proposal(s) awaiting approval

  --- Proposal #0 ------------------------------
    id:           job-1042
    label:        reindex shard 7
    action:       reindex
    cost:         6.00
    created_at:   2026-08-18T22:14:07Z

  --- Proposal #1 ------------------------------
    id:           job-1043
    label:        reindex shard 12
    action:       reindex
    cost:         6.00
    created_at:   2026-08-18T22:14:07Z

  Use approve(index) or reject(index) to decide.

> approve 0, reject 1

  Approved and queued for execution: reindex shard 7
  Rejected and removed: reindex shard 12

Output above is illustrative.

Notes on safety

• run_command runs arbitrary shell on the remote host. It exists because the alternative is opening a terminal anyway, but it is the most dangerous tool here. Scope the SSH user to what it actually needs rather than running everything as root.
• wallet_balance is read-only and never touches a key. If you do not configure it, it does not exist.
• Nothing in this repo stores a credential. RPC URLs carry provider keys in the path, so keep EVM_RPC_URL in the environment and out of your config files.
• StrictHostKeyChecking is set to accept-new: unknown hosts are trusted on first connect, changed host keys still fail. Set it to yes and pre-populate known_hosts if you want the stricter behavior.

License

MIT