MCP

MCP Setup and Documentation

Unfour runs a local stdio MCP server that lets compatible MCP clients use approved workspace-scoped API, SSH, database, activity, and system capabilities through the same command and policy boundaries as the desktop app.

Requirements

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.

Codex setup

Open Settings → MCP in Unfour.
Under Codex, choose Configure Codex. Unfour detects the installed MCP command, safely merges the Codex configuration, and reports the status.
Restart Codex after configuration changes.

For manual setup, choose Copy command in Settings → MCP, replace the placeholder below with that exact value, and add the entry to the Codex TOML configuration.

Codex config.toml

[mcp_servers.unfour]
command = "PASTE_COMMAND_FROM_SETTINGS_MCP"
args = []

Cursor setup

Open Settings → MCP in Unfour.
Under Cursor, choose Configure Cursor. Unfour detects and safely merges the project or user MCP configuration.
Restart Cursor after configuration changes.

For manual setup, choose Copy command and replace the placeholder below. Save this object in .cursor/mcp.json for a project or ~/.cursor/mcp.json for the user.

Cursor mcp.json

{
  "mcpServers": {
    "unfour": {
      "command": "PASTE_COMMAND_FROM_SETTINGS_MCP",
      "args": []
    }
  }
}

Other MCP clients

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

Capabilities

Workspace

Inspect the active workspace and manage supported workspace variables. Representative tools include unfour.workspace.current and unfour.workspace.list_variables.

API

Inspect saved requests and redacted history, then send an approved request. Representative tools include unfour.api.list_requests and unfour.api.send_request.

SSH

Inspect history and tasks, run diagnostics or commands, and read or change remote files within policy. Representative tools include unfour.ssh.list_history and unfour.ssh.run_diagnostic.

Database

List saved connections, browse structure, run read-only queries or explain output, and execute policy-controlled SQL. Representative tools include unfour.db.list_connections and unfour.db.query_readonly.

Activity and system

Review recent redacted local activity and storage readiness with unfour.activity.list and unfour.system.health.

Permissions and confirmation

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.
High-risk actions return CONFIRMATION_REQUIRED instead of running immediately.
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.

Credentials and the local-first boundary

The MCP process opens the same local Unfour database as the desktop app and resolves credentials from the operating-system credential store only when a saved API, SSH, or database operation needs them.

Raw credential values are never returned by MCP tools.
SSH passwords, private-key paths and passphrases, database passwords, and local credential references remain device-local.
Cloud Sync does not synchronize secrets, credential references, local paths, or runtime history; those values must be configured 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.

Troubleshooting

Client cannot find Unfour

Open Unfour once, confirm Settings → MCP shows the MCP command as available, configure the client again, and restart it.

Wrong command or config

Copy the current command from Settings → MCP. Keep args empty and remove stale development or WindowsApps paths.

Local data is missing

Start the desktop app once and verify that the client is using the same Stable, Test, or Dev storage profile. Do not use ephemeral mode.

Configuration changed

Restart the MCP client so it opens a new stdio process with the updated command.

Tool is blocked

Check the active workspace, environment, explicit MCP policy, and whether the action is read-only, guarded, or requires confirmation.