Install · configure · check it worked

Getting it
running

Everything in order, from an empty machine to an agent whose writes you can take back. Nothing here is needed twice: once a client is pointed at the proxy, it stays pointed at it.

Your first
undo

One folder, one rule, one mistake put back. About ten minutes. Every line of output below is what these commands actually print — nothing here is illustrative.

Install it

This is for you — the screen, undo, watch. Your agent needs nothing installed: the config later on fetches the proxy on demand.

npm install -g synartesis
Put a folder under guard

Pick somewhere real but survivable. init asks the server what it can do. This one it recognises, so it uses the policy that ships here and checks every rule against what the server actually advertises. A server it does not know gets every tool guarded, because a tool nobody has said how to undo is one your agent should not be using alone.
from anywhereone policy, in your home
```
$ synartesis init fs -- npx -y @modelcontextprotocol/server-filesystem ~/notes

   WROTE  ~/.synartesis/synartesis.yaml

  Recognised 14 tools, so the policy that ships for filesystem was used.
  Read it before you trust it.
```
That last path is the one thing to choose: everything under it is what your agent can read and write, and nothing outside it exists as far as the server is concerned. Name a real directory you would mind losing but could survive — ~/notes, ~/Documents/drafts, ~/code/some-project. Pass more than one to allow more than one.
Read the one rule that matters

The filesystem server is one it knows, so this is already written. Open the file and find fs.write_file — it is the whole idea in eight lines, and the shape you will write yourself for a server it does not recognise. snapshot is what to read before the call; inverse is the call that puts that back. $.path is an argument the agent passed; $snapshot.content is what the pre-read found. And absent_when is what this server says when the thing is not there — without it, a file that exists but cannot be read looks identical to one being created, and gets offered for approval as though it were.
~/.synartesis/synartesis.yamlan unrecognised server, before you fill it in
```
- match: "fs.write_file"
  class: irreversible
  gate: always
```
~/.synartesis/synartesis.yamlwhat a finished rule looks like
```
- match: "fs.write_file"
  class: reversible
  snapshot:                        # read this first
    tool: "fs.read_text_file"
    args:
      path: "$.path"
    absent_when: ["ENOENT", "no such file"]   # what "not there" sounds like
  inverse:                         # and this puts it back
    tool: "fs.write_file"
    args:
      path: "$.path"
      content: "$snapshot.content"
```
Check it before you trust it

check starts every server and asks whether the tools your policy names actually exist. One reversible tool is enough to begin; the three still guarded will simply stop and ask.
synartesis checkbefore anything is running
```
$ synartesis check

   POLICY  ~/.synartesis/synartesis.yaml

  servers  fs
  policies 10 readonly, 1 reversible, 3 irreversible
  guarded  3
```
Point your agent at the proxy, not the server

One entry, however many servers your policy covers. Then work normally: ask your agent to tidy the folder, rewrite a file, whatever you would have asked anyway.
.mcp.jsonthe same block in any client
```
{
  "mcpServers": {
    "synartesis": {
      "command": "npx",
      "args": ["-y", "synartesis", "proxy",
               "--manifest", "/Users/you/.synartesis/synartesis.yaml"]
    }
  }
}
```
Put it back

Your agent overwrites roadmap.md with something you did not want. Look first with --dry-run; both default to the most recent run, so there is usually no id to type. The line that matters is state matches — it read the file again and confirmed nothing else had changed it since.
synartesis undothe file comes back
```
$ synartesis undo

    1  revert           fs.write_file  state matches; applying inverse
       called fs.write_file {"path":"~/notes/roadmap.md",
         "content":"# Roadmap\n\nQ3: ship the undo layer.\n"}

   RESULT  rolled_back
```

Where the
config goes

Synartesis speaks MCP in both directions and never learns who is on the other end — a thirty-six line script with no SDK drives it the same as any editor does. So the block is the same in every client; what differs is which file it goes in, and every path here was checked against that client’s own documentation. Add the entry, restart the client, and the tools appear under Synartesis instead of under the server.

Claude Code

One command, no file to find. Or write .mcp.json at the root of a project to share it with everyone working on that repo.
terminalanywhere
```
$ claude mcp add synartesis -- npx -y synartesis proxy \
    --manifest ~/.synartesis/synartesis.yaml
```

Claude Desktop

Settings → Developer → Edit Config opens this file, creating it if it is not there. Quit and reopen the app afterwards — it only reads the file at startup.

claude_desktop_config.jsonmacOS · Windows

~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synartesis": {
      "command": "npx",
      "args": ["-y", "synartesis", "proxy",
               "--manifest", "/Users/you/.synartesis/synartesis.yaml"]
    }
  }
}

Cursor

~/.cursor/mcp.json for everywhere, .cursor/mcp.json in a project for just that one. Cursor wants the transport named explicitly.

~/.cursor/mcp.jsonnote the type field

{
  "mcpServers": {
    "synartesis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "synartesis", "proxy",
               "--manifest", "/Users/you/.synartesis/synartesis.yaml"]
    }
  }
}

Codex CLI

OpenAI’s local agent, which does run stdio servers. One command, and it writes the TOML below into ~/.codex/config.toml for you. codex mcp list shows it afterwards.

terminalopenai codex

$ codex mcp add synartesis -- npx -y synartesis proxy \
    --manifest ~/.synartesis/synartesis.yaml

  Added global MCP server 'synartesis'.

~/.codex/config.tomlwhat that writes

[mcp_servers.synartesis]
command = "npx"
args = ["-y", "synartesis", "proxy", "--manifest", "/Users/you/.synartesis/synartesis.yaml"]

Anything else, and one that will not work

Any client that runs a local MCP server takes the same two fields, whatever it calls its config file. ChatGPT is the one that will not: its connectors accept a remote HTTPS endpoint only and will not start a process on your machine, so a command entry has nowhere to go. For that, serve the proxy over HTTP instead — it refuses to start without a token, and binds to loopback until you say otherwise.
an endpoint instead of a process/mcp, bearer token
```
$ synartesis proxy --manifest ~/.synartesis/synartesis.yaml \
    --http 9123 --token "$SYNARTESIS_TOKEN"

  a session that goes quiet for half an hour is closed;
  --http-idle changes that
```
Reaching that from the internet means a tunnel in front of it, and that stays your decision rather than a flag. What is on the other end can write through every server in your policy: treat the token like a password, and prefer a tunnel that does its own authentication.

Telling whether
it worked

The failure worth knowing about is the quiet one: your agent connects, ignores the tools, and uses its own instead. Nothing errors. Nothing is recorded.

Ask the agent to do something, then look

Leave synartesis watch running in a second terminal. Rows appear as calls happen. A live run beside zero actions is the diagnostic — it means your agent connected and then did the work with its own file tools. Name the tools you want it to use, or take the built-in ones away.
synartesis watchsecond terminal
```
$ synartesis watch

  ⧗ watching  1 runs, 1 live  ·  0 recent actions
        ↑ connected, and not being used
```
When the server will not start

Run the same command by hand: whatever it prints is what your client saw and hid. check starts every server in the policy and reports which named tools do not exist. Claude Desktop keeps per-server logs, and they are the fastest answer when a connector simply never appears.
three places to lookin this order
```
$ synartesis check
$ npx -y synartesis proxy --manifest ~/.synartesis/synartesis.yaml
$ tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```
Paths, which are most of it

Use absolute paths in the config — a client does not start in the directory you think it does, and ~ is not expanded inside a JSON string. Give --manifest the real path. If npx cannot be found, the client is running with a smaller PATH than your shell: give the full path to npx, or install with npm install -g synartesis and use synartesis directly.

Getting itrunning

Your firstundo

Install it

Put a folder under guard

Read the one rule that matters

Check it before you trust it

Point your agent at the proxy, not the server

Put it back

Where theconfig goes

Claude Code

Claude Desktop

Cursor

Codex CLI

Anything else, and one that will not work

Telling whetherit worked

Ask the agent to do something, then look

When the server will not start

Paths, which are most of it

Getting it
running

Your first
undo

Where the
config goes

Telling whether
it worked