mcpgawkdocs ← Site

Quickstart

Six 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 · Check a server before you add it

mcpgawk scan --http https://example.com/mcp
mcpgawk scan --stdio "npx -y <server>"

Point it at the server's URL, or the command your agent would run. Nothing is added to any agent's config.

You should see what the server's tools can do: which can change data, which take a destination from the caller, and what they cost in context. The first scan records this as the server's baseline. Scan it again later and mcpgawk tells you if anything changed, and prints the exact mcpgawk approve command to accept the change.

3 · Check every server you already have

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.

4 · 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.

5 · 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.

6 · See what changed, later

mcpgawk changes

Every scan records a snapshot. Once a server’s tools move between two snapshots — a tool added, a schema widened, a description rewritten — this screen shows exactly what, and when. On the first day it says No history yet; that is expected. On one fleet, five third-party servers changed nineteen times in six weeks, and one of those changes added a tool that rotates API keys.

    ⟳ 2026-09-02 18:13  resend changed  (previous snapshot 2026-08-24 19:12):
        ! tool input schema CHANGED: create-webhook
        + tools added: get-webhook-event, list-webhook-events, update-segment, ...

Next