Quickstart
Four steps. Each one says what you should see, and what to do when you do not.
1 · Install
uv tool install --force mcpgawk
You should see the install finish, then mcpgawk --version printing a
version. No uv? curl -LsSf https://astral.sh/uv/install.sh | sh,
or use pipx install --force mcpgawk.
If you get command not found: the install worked but its
folder is not on your PATH. Open a new terminal first — the shell caches
its path list. If it still fails, python3 -m mcpgawk always works, and proves the
package is fine and only the shortcut is missing.
2 · Run it
mcpgawk
No arguments. It reads every agent config on the machine and lists every server in it.
You should see a table of servers with a state each, then a summary line, then an offer to open the panel.
Before it launches anything local, it asks. Scanning a stdio server means running its code, so consent is explicit. A non-interactive run — CI, or an agent — always defaults to deny, and an unrecognised answer is never taken as yes.
If it sits there for minutes, a local server is slow to start, usually a first-run
npx download. Give it up to three minutes, then Ctrl-C.
If it finds nothing, run mcpgawk status: it names every client it looked at
and what it found, including configs it could not read, so "you have none" and "it could not
see them" are distinguishable.
3 · Turn protection on
mcpgawk guard install
This installs one pre-execution hook. Every MCP tool call your agent makes is then checked against the baseline you approved, locally, before the call runs.
You should see a confirmation naming the settings file it wrote to. Check it any time
with mcpgawk guard status.
Only 6 of the 21 supported clients have a hook
point, so guard install protects only those. Check yours on
Clients. For the rest, route the client through the
gateway — same approved baseline, checked at the endpoint.
4 · See the whole machine
mcpgawk panel
Opens a local page: every server, every decision, every piece of evidence.
The buttons only work through the link printed in your terminal. That link carries a one-session token. Open the bare URL — or let an agent open it — and the page is read-only. Approving moves trust, so it needs the person at the keyboard.
Next
- Every command and flag
- When something goes wrong
- Try the whole story end to end, safely:
mcpgawk demoplants a deliberately-bad server in a sandbox, approves it, turns it hostile, and blocks the tool that appeared afterwards. It touches nothing real.