# 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](https://github.com/jlowin/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

```bash
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:

```bash
fastmcp dev server.py
```

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

```json
{
  "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:

```json
[
  {
    "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:

```json
{
  "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:

```python
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:

```json
{
  "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:

```python
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