Pre-release · preparing for Mac App Store submission

AIAgentGate Documentation

Last updated: 22 August 2026

AIAgentGate reads the AI-agent and MCP configuration on your Mac, reports what carries risk, and tracks how that changes over time. This page covers how each part works and where the boundaries are.

Granting access

AIAgentGate looks for known agent configuration locations in your home folder and asks for access to each one individually through a standard macOS open panel. It reads only what you grant, and each grant is remembered, so you are asked once rather than every run.

Access is per location rather than all-or-nothing, for the same reason the app complains about over-broad filesystem roots elsewhere: a tool that audits over-permissioned configuration should not begin by asking for your whole disk. There is no scan-everything mode, and it can reach nothing you have not granted.

The locations it knows about are ~/.claude, ~/.claude.json, ~/.codex, ~/.cursor, ~/.gemini, and two under ~/Library/Application Support.

You cannot point it at an arbitrary folder yet

This version offers that fixed list and no “add a folder” control. When you grant a location the panel opens at that path, and if you navigate away and pick something unrelated the grant is refused rather than accepted — a deliberate check so a stray selection cannot silently widen access, but it does mean an arbitrary folder cannot be granted today.

So a configuration outside your home folder — a repo on an external volume, something under /opt, or a machine that is not yours — is out of scope for now. Support for choosing your own location is the next thing being built.

What it inventories

For every MCP server it finds, the app records:

the command it runs, and its parsed arguments — read as arguments rather than as one opaque string, so a filesystem root buried behind several flags is recognised as a root;
the transport it uses;
the names of environment variables it expects — names only, never values, so the audit does not become one more place your secrets are written down;
the filesystem roots it declares;
the remote endpoints it names.

Reading, never running

The app never starts an MCP server and never executes a command it finds in a configuration file. Commands are text to be parsed, not instructions to follow.

Finding types

Every finding names the file and the configuration that produced it, so you can check the reasoning rather than trust the label.

Finding	What it means, and what to do
Plaintext credential	A secret is written directly into a configuration file rather than referenced from somewhere safer. Move it out and reference it by environment variable name. Treat any key that has sat in a file like this as worth rotating.
Over-broad filesystem root	A server is granted much more of your disk than the work plausibly needs — often a home directory where a project directory would do. Narrow the root to the project.
Shell or interpreter invocation	The server is launched through a shell or an interpreter, so the command that actually runs is not the one written in the config, and can change without the config changing. Invoke the binary directly where you can.
Floating package tag	The entry fetches whatever version is current at launch, so what runs tomorrow is not what you reviewed today. Pin a version.
Remote endpoint with no declared auth	A configured endpoint with nothing in the configuration describing how it authenticates. It may be authenticating by some means the file does not record — worth confirming rather than assuming either way.
Duplicate tool name	Two servers expose the same tool name, so which one answers a call is not obvious from the configuration. Rename one, or remove the server you did not mean to keep.
Unparseable file	A configuration file the app could not read. Reported rather than skipped, because a file passed over in silence would misrepresent how complete the audit is. Usually a syntax error or an unsupported format.

Baselines and diffs

Once you have been through the findings and decided what you are content with, save a baseline. Later runs compare against it and show what changed rather than making you read the whole inventory again: a server that appeared, a root that widened, a tag that started floating.

You can also mark a finding as an accepted risk. It stays visible as accepted rather than vanishing — the point is that a later reader can see the decision was made deliberately, not that the finding never existed.

The exported report

Export produces a report suitable for handing to a security reviewer. It is redacted by default: no absolute paths, and no secret values.

Why redaction is the default

A report about credential hygiene that contained the credentials would be self-defeating, and absolute paths leak usernames and project names. The redacted export is the version that is safe to attach to a ticket — which is the whole point of having one.

The file goes wherever you save it. The app does not send it anywhere; it makes no network connection at all.

The fix flow

Where a finding has an unambiguous remedy, the app can apply it for you. Every fix follows the same sequence:

Back up the file before touching it.
Apply the change.
Validate the result.
Roll back from the backup if validation does not hold up.

Nothing is edited without your say-so, and the backup remains after the fix so you can go back later.

JSON only

Fixes apply to JSON configuration only. TOML files — including Codex's config.toml — are inventoried and reported, but not edited. You will see the findings and make those changes yourself.

Limitations

Worth knowing before you rely on it:

It audits configuration, not behaviour. It reads config files; it does not watch an agent run. What it reports is what your setup declares or permits, not a record of what any agent actually did.
It is not a runtime guard. It does not sit between an agent and your files and cannot prevent an agent from doing anything. Nothing it reports is enforced by it.
Fixes are JSON-only. As above — TOML is reported, not edited.
Known locations only. This version audits a fixed list of agent configuration locations in your home folder. You cannot point it at a folder of your own choosing yet — see Granting access.
Coverage is what you granted. The app audits the locations you granted. A clean report means nothing flagged in what it could see.