# 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](https://trygoodfolder.com/docs/services.md).

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

```bash
npm install -g @goodfolder/mcp
```

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

```bash
codex mcp add goodfolder -- goodfolder-mcp
```

For Claude Code:

```bash
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`:

```json
{ "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](https://trygoodfolder.com/docs/self-hosting.md) 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.

```bash
codex mcp add goodfolder --env GF_API_URL=http://localhost:4100 -- goodfolder-mcp
```

## Resources

- [Product and pricing](https://trygoodfolder.com/#pricing)
- [Public source](https://github.com/areia-ai/goodfolder)
- [Self-hosting guide](https://trygoodfolder.com/docs/self-hosting.md)
- [Local MCP reference](https://github.com/areia-ai/goodfolder/blob/main/apps/mcp/README.md)