Start

Quickstart

Install limited beta fourgate 0.4.0b1, run fourgate demo, and read PASS, FAIL and UNKNOWN.

View source on GitHub (opens in a new tab)

On this page

Install#

Limited beta 0.4.0b1 needs Python 3.10–3.13 on Linux or Windows. It is local command-configured stdio only. Install the pre-release from PyPI (opens in a new tab):

Shell

$ python -m pip install --pre "fourgate==0.4.0b1"

Expected output of python -m fourgate --version is fourgate 0.4.0b1. If fourgate is not on PATH, python -m fourgate is the same command.

Alternatives#

Install the same pre-release from its git tag:

Shell

$ python -m pip install "git+https://github.com/hifzabuildsai/fourgate@v0.4.0b1"

Or install the built wheel attached to the v0.4.0b1 GitHub pre-release (opens in a new tab) after checking its SHA-256, with python -m pip install fourgate-0.4.0b1-py3-none-any.whl.

Stable PyPI 0.3.0 is still installable without --pre. Use 0.4.0b1 for the current limited beta.

Check the install:

Shell

$ fourgate --version

To install from a clean checkout of the repository instead, run python -m pip install . in it. The bundled fixture used further down needs the checkout.

Run the demo#

Shell

$ fourgate demo

One command, no API keys, no network. It runs five real MCP sessions against a demo connector, the guarded ones through a real fourgate guard process, then a self-check and a local summary page at ./fourgate-demo/fourgate-demo-summary.html. Add --pace 2 to slow it down for screen recording.

The connector is simulated: a local file stands in for the system of record. The five sessions:

Without Fourgate. The broken connector returns Created ISSUE-001, but the system of record has 0 issues.
Enforce mode, broken connector. The agent receives an [FOURGATE] outcome_failed verdict (record_missing) first, with the original Created ISSUE-001 preserved behind it.
Enforce mode, healthy connector. The issue exists, the response passes through unchanged, and the log records PASS.
Shadow mode, broken connector. The agent receives exactly what it got without Fourgate. The log still records FAIL with record_missing.
Enforce mode, system of record unreachable. Fourgate cannot confirm either way, records UNKNOWN (never PASS), and does not block the call.

You can step through a recorded run on the demo page and open the sample summary page it wrote.

What PASS, FAIL and UNKNOWN mean#

Verdict	Meaning	What the agent receives
PASS	The independent read-back found the record with the contracted values.	The connector response, unchanged.
FAIL	The read-back proved the record missing (`record_missing`) or different (`field_mismatch`).	In shadow mode, nothing different. In enforce mode, one attributed `outcome_failed` verdict ahead of the connector's original content.
UNKNOWN	Fourgate could not confirm either way: a verifier crash, timeout, malformed output, missing selector, or an internal fault.	The connector response, unchanged. Fourgate fails open.

UNKNOWN is never counted as PASS. fourgate scan exits non-zero on it. See why UNKNOWN is never PASS.

Optional: scan the bundled fixture#

This needs a checkout of the repository, because the fixture lives there. fourgate scan calls the write tools named in a contract, so it must only ever run against a disposable test account. Here the target is a local demo server, and the account label is disposable-demo.

Shell

$ export FOURGATE_DEMO_STORE="$(mktemp -d)/issues.json"$ export FOURGATE_DEMO_MODE=broken$ fourgate scan fixtures/contracts/scan_demo.json \  --confirm-test-account disposable-demo --report-dir ./fourgate-output

The expected result is FAIL / record_missing with exit code 1, and a fourgate-report.json plus a self-contained fourgate-report.html in ./fourgate-output. Set FOURGATE_DEMO_MODE=healthy and rerun with a fresh store path to see PASS and exit code 0. PowerShell syntax is on the Windows notes page.

Next#

Protect your first tool walks the same flow against your own MCP server: init, doctor, scan, guard, summary.