Use GoodFolder with an agent

A history for your files

GoodFolder gives a folder on your computer a history you can read. Save records what changed and who changed it; Sync carries that history between computers, and Restore records a return as a new Save. Your files stay where they are and keep their formats.

Documents, spreadsheets, presentations, PDFs, images, video, audio, notes, and HTML pages share the same history. The browser previews office documents without rewriting their originals. Web pages can run JavaScript in an isolated preview.

Set up the local MCP server

The GoodFolder MCP server runs over stdio on a computer that can access your folder. That is the right setup for an agent working beside your files.

An assistant that runs somewhere else — a hosted service, a cloud runner — can reach the same tools over HTTP with a scoped key of its own, so it never sees more of your account than you approved. See Connect a service or cloud assistant.

Install it from npm (Node.js 22 or newer):

npm install -g @goodfolder/mcp

Add the server to Codex with the command below. For another MCP client, configure goodfolder-mcp as the command.

codex mcp add goodfolder -- goodfolder-mcp

For Claude Code:

claude mcp add --scope user goodfolder -- goodfolder-mcp

Approve access and connect a folder

Ask your agent to call goodfolder_connect with the absolute path of a folder you want to protect. The first connection on the computer opens a browser for you to approve access. Hosted accounts need an active trial or subscription before connecting a new folder.

Use the local MCP server for a folder already on your computer. Connecting preserves its name and location. After connecting, ask for goodfolder_log to read its Timeline. When you want to record work, explicitly ask the agent to use goodfolder_save; use goodfolder_sync to carry saved changes between computers.

A goodfolder_save reply says what happened in a form an agent can read, not only in text:

warnings lists saved files whose names suggest a secret. The save still happened; only the files it added or changed are looked at, so an empty list is not a promise that the folder holds none.
skipped lists what stayed out of the save and the rule for each: a built-in rule, the folder's .goodfolderignore, or the project's own settings.
If GoodFolder refused the save — because it added a file shaped like a credential or one on the ignore list — the reply carries refusal with each path and rule, and nothing from that save was kept.

For example, these are the arguments to goodfolder_connect:

{ "folder": "/absolute/path/to/your-folder" }

Review work in the browser

The dashboard exposes WebMCP tools to compatible browser assistants. They can inspect files and history, add comments, and prepare Change Proposals for human review. They cannot accept proposals, Save, Sync, Restore, delete folders, invite people, or change access.

A dashboard proposal does not change the original file. The person responsible for the folder reviews and accepts the work. These browser permissions are separate from the local MCP server, which can change the folder when you ask it to.

Run your own server

Docker Compose runs the GoodFolder services without a cloud account, mail provider, billing provider, or AI key. Follow the self-hosting guide to configure and start them.

For the default Docker Compose setup, set GF_API_URL to http://localhost:4100 in the MCP process environment before connecting a new folder. If you have no email provider, the server log contains the one-time sign-in link. Open it yourself to approve access.