MCP Setup and Documentation

• ✓ Install Unfour and open the desktop application once so its local database exists.
• ✓ Create or select the workspace whose saved resources the MCP client should use.
• ✓ Install an MCP client that supports a manually configured local stdio server.
• ✓ Keep the command shown by Settings → MCP available. Standard installs use the installed sidecar path; Microsoft Store/MSIX installs use the stable unfour-mcp.exe execution alias.

1. 1 Open Settings → MCP in Unfour.
2. 2 Under Codex, choose Configure Codex (recommended). Unfour merges the unfour entry into ~/.codex/config.toml in your user home directory and reports the status.
3. 3 Restart Codex after configuration changes.

Automatic configuration writes only that user-level file; it does not update project configuration or a custom CODEX_HOME. It preserves unrelated configuration, backs up an existing file, and refuses invalid TOML. It does not change workspace permissions or start tool calls.

For manual setup, copy the executable path or alias from Settings → MCP. The paths below are illustrative: replace them with your copied value. Codex launches the executable directly, even when its Windows path contains spaces; keep args empty. In a TOML single-quoted literal string, backslashes stay literal.

[mcp_servers.unfour]
command = 'D:\Program Files\Unfour\unfour-mcp.exe'
args = []

Alternatively, a TOML double-quoted basic string must escape each Windows backslash as \\. The two examples decode to the same executable path; use only one unfour entry.

[mcp_servers.unfour]
command = "D:\\Program Files\\Unfour\\unfour-mcp.exe"
args = []

For Microsoft Store/MSIX, use the stable execution alias below. On macOS or Linux, put the exact path copied from Settings → MCP in command and keep args empty.

[mcp_servers.unfour]
command = "unfour-mcp.exe"
args = []

1. 1 Open Settings → MCP in Unfour.
2. 2 Under Cursor, choose Configure Cursor (recommended). Unfour merges the unfour entry into ~/.cursor/mcp.json in your user home directory and reports the status.
3. 3 Restart Cursor after configuration changes.

Automatic configuration writes only the user-level file, not a project’s .cursor/mcp.json. It preserves unrelated configuration, backs up an existing file, and refuses invalid JSON. Project-level setup is a manual option: merge the unfour server entry into the project file yourself rather than replacing other servers.

For manual setup, use Copy command in Settings → MCP. On Windows, if the executable path contains whitespace, use command = cmd.exe and two args: /c, then the complete path as one string. JSON must escape each backslash as \\. Replace the illustrative path below with your copied path; do not split it at spaces or add embedded quote characters.

{
  "mcpServers": {
    "unfour": {
      "command": "cmd.exe",
      "args": ["/c", "D:\\Program Files\\Unfour\\unfour-mcp.exe"]
    }
  }
}

Here /c and the path are arguments to cmd.exe; unfour-mcp itself takes no CLI arguments. For Microsoft Store/MSIX, use the stable alias directly with empty args, as below. For Windows paths without whitespace and for macOS/Linux, put the copied executable path directly in command with empty args; preserve JSON escaping.

{
  "mcpServers": {
    "unfour": {
      "command": "unfour-mcp.exe",
      "args": []
    }
  }
}

Other MCP-compatible clients that support a manually configured local stdio server may also connect.

Restart your MCP client or its Unfour server after updating so it loads the updated binary. Select the intended workspace, inspect its policy, and list resources before changing them. Resource management is part of the Free core.

• ✓ Create a workspace with unfour.workspace.create, or rename one with unfour.workspace.rename using expectedName from workspace.list. Creation does not activate it or copy resources; it inherits the authorizing workspace’s environment type and MCP policy, with no policy override.
• ✓ Use unfour.api.list_folders before creating, renaming, moving, reordering, or deleting folders. Folder moves stay within a collection; request moves stay within a workspace. Renames use expectedUpdatedAt. Recursive deletion also removes descendant folders and requests; review the scope and any required confirmation.
• ✓ Use unfour.api.move_request or unfour.api.duplicate_request to organize the original saved request without rebuilding it from a masked preview. These operations do not send HTTP traffic.
• ✓ Use unfour.db.list_saved_sql and get_saved_sql to inspect records, then save_saved_sql or delete_saved_sql to manage them. Update/delete requires expectedRevision; omitted update fields preserve their original values. These tools do not execute SQL. Use unfour.db.list_catalogs with a saved connection to discover its available catalogs.

unfour.ssh.write_file and unfour.ssh.patch_file use a saved SSH connection under workspace policy. They support regular files only and reject observed symlinks and directories. Review the exact target and content, and complete any required confirmation.

• ✓ write_file uses SFTP without a terminal session or remote Python. Replacing an existing file requires [email protected] version 1; unsupported servers fail before replacement.
• ✓ patch_file needs remote python3 through a POSIX-compatible SSH shell. Default Windows cmd/PowerShell SSH shells are not covered.
• ✓ Write content or combined patch search/replacement is limited to 4 MiB of UTF-8 bytes. Patch target and result files are limited to 16 MiB.
• ✓ New files use mode 0600. Replacement preserves basic owner/group/mode, but not extended ACLs, attributes, or hard-link identity.

Every tool call is checked against the target workspace MCP policy. The default auto policy maps dev to ordinary full access, test to guarded access, and prod to read-only access with safe SSH diagnostics.

• ✓ Read-only, destructive, idempotent, and open-world hints describe each tool, but server-side policy is the final control.
• ✓ Where policy or backend safety requires confirmation, the call returns CONFIRMATION_REQUIRED. Full access does not guarantee a prompt for every risky action; explicit workspace policy overrides auto.
• ✓ After reviewing the exact target and payload, the client retries the same call with confirm=true and the returned confirmation_text.
• ✓ The confirmation text is bound to the payload fingerprint; changing SQL, URL, command, path, or patch content requires a new confirmation.
• ✓ Results and activity are redacted or masked where needed. Production defaults do not grant autonomous write access.

The Flow tools share the desktop definitions, saved workspace resources, and run history. Select the workspace and environment explicitly, review the definition and inputs, then confirm the run. Flow execution requires confirmation even under full_access and is blocked under read_only, including runbooks made of read-only checks. Cancel does not undo effects; keep the MCP connection alive during a run.

MCP uses the same local database and command bus as the desktop app. SSH and database credentials are resolved through the OS secret store when needed. Saved API configuration has a separate local-storage and snapshot-redaction boundary; it is not automatically keychain-backed.

• ✓ MCP policy blocks secret-reveal operations. Rule-based masking does not guarantee that arbitrary logs, query results, or other tool output contain no confidential text.
• ✓ SSH passwords, private-key paths and passphrases, database passwords, and local credential references remain device-local.
• ✓ Cloud Sync excludes connection credentials/references, device-local paths, runtime history, and secret-marked variable values, and redacts recognized API secrets. Review scripts and free text before enabling sync; configure omitted values on each device.
• ✓ Do not enable UNFOUR_MCP_STORAGE_MODE=ephemeral for daily use. It creates an empty in-memory registry intended for CI and protocol checks.