Connect an agent

Resurf connects as a local MCP server. Your agent starts the resurf program on this Mac and talks to it over standard input and output; nothing listens on the network.

Every setup below runs the same command: the full path to resurf, then mcp serve, --vault with the path to your library, and --allow-write when any Access switch is on. The app fills in both paths for you. The program is usually /Applications/Resurf.app/Contents/Helpers/resurf. On this page they're written /path/to/resurf and /path/to/Resurf Library.

Click Copy setup command and run it once in Terminal. It needs the claude command. Then start a new Claude Code session.

claude mcp add --scope user resurf -- '/path/to/resurf' mcp serve --vault '/path/to/Resurf Library' --allow-write

--scope user makes Resurf available in every folder, not just the one Terminal is in. If Resurf is already added, remove it first, then run the setup command again. To remove it:

claude mcp remove --scope user resurf

Click Add to Claude. A panel asks for Claude's settings folder: select the Claude folder in Library → Application Support and click Allow setup. If it's missing, open Claude once, then try again. Then quit Claude completely and reopen it.

Resurf adds itself under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json and leaves your other servers alone. To remove it, open Claude → Settings → Developer → Edit Config, delete the resurf entry under mcpServers, and restart Claude.

Click Add to Cursor, then approve the install in Cursor. Check Cursor Settings → Tools & MCP for the connection and its tools.

If Cursor doesn't open, Resurf offers Copy configuration instead: merge it into ~/.cursor/mcp.json.

{
  "mcpServers" : {
    "resurf" : {
      "args" : [
        "mcp",
        "serve",
        "--vault",
        "/path/to/Resurf Library",
        "--allow-write"
      ],
      "command" : "/path/to/resurf"
    }
  }
}

To remove it, delete resurf in Tools & MCP, or from ~/.cursor/mcp.json.

Click Add to VS Code and approve the install, then start Resurf from MCP: List Servers in the Command Palette.

If VS Code doesn't open, paste the configuration into MCP: Open User Configuration. VS Code calls the list servers, not mcpServers.

{
  "servers" : {
    "resurf" : {
      "args" : [
        "mcp",
        "serve",
        "--vault",
        "/path/to/Resurf Library",
        "--allow-write"
      ],
      "command" : "/path/to/resurf"
    }
  }
}

To remove it, choose MCP: List Servers, pick resurf and remove it, or delete it from that file.

Click Copy setup command and run it once in Terminal. It needs the codex command. Then start a new Codex session.

codex mcp add resurf -- '/path/to/resurf' mcp serve --vault '/path/to/Resurf Library' --allow-write

Resurf is saved as [mcp_servers.resurf] in ~/.codex/config.toml. When Access lets the agent change things, you can ask Codex to confirm each change by adding this inside that section:

default_tools_approval_mode = "prompt"

To remove it, run codex mcp remove resurf, or delete the section.

Click Copy setup command and run it once in Terminal. It needs the gemini command. Then start a new Gemini session, and run gemini mcp list to check the connection.

gemini mcp add --scope user resurf '/path/to/resurf' -- 'mcp' 'serve' '--vault' '/path/to/Resurf Library' '--allow-write'

--scope user saves it for every folder; without it, Gemini writes a settings file into whatever folder Terminal is in. To remove it, run gemini mcp remove --scope user resurf.

Pick Any MCP client under More agents and click Copy configuration. Choose a local, stdio server in the client. If it reads an mcpServers block, merge this into its MCP settings:

{
  "mcpServers" : {
    "resurf" : {
      "args" : [
        "mcp",
        "serve",
        "--vault",
        "/path/to/Resurf Library",
        "--allow-write"
      ],
      "command" : "/path/to/resurf"
    }
  }
}

If its settings have separate fields, enter /path/to/resurf as the command and these as the arguments, one per entry:

[
  "mcp",
  "serve",
  "--vault",
  "/path/to/Resurf Library",
  "--allow-write"
]

Some clients name the block differently; follow their MCP settings. To remove it, delete the resurf entry from the client's MCP settings.

• Connected means the agent is set up for this library. Under it, Active now means the agent has Resurf running right now, and Last used says when it last did.
• Check setup means the agent last connected to a different library, or couldn't open this one. Click Set up again.
• To test the server itself, expand Advanced and click Test beside Server. It starts Resurf the way an agent does and reports the version, how many tools it offers, and whether they're read-only or read and write.

Resurf reads the Access switches on every call, so turning one off takes effect at once, even for an agent that's already running.

Turning one on is different if the agent was set up with every switch off: its command has no --allow-write, so it can only ever read. Turn the switch on, then click Set up again and repeat the setup.