@mergesafe-io/connect

One command connects every AI client on your machine to the MergeSafe MCP server — globally, so it works in every project. No config editing.

npx @mergesafe-io/connect --key msk_your_api_key

That's it. The CLI detects which clients are installed (Claude Code, Claude Desktop, Codex, Cursor, Windsurf, VS Code, …), writes each one's global config, and backs up every file it touches. Restart your clients and the mergesafe tools are available everywhere.

To uninstall from every detected client:

npx @mergesafe-io/connect --uninstall

That removes only the mergesafe entry — all other configs are preserved.

What it does

• Detects the AI clients installed on your machine (or targets just one if you name it: npx @mergesafe-io/connect cursor --key msk_…)
• Finds the right global MCP config file for each client and OS
• Backs up the existing file next to it (*.bak-<timestamp>)
• Merges in the mergesafe server entry — every other setting and server is preserved
• Refuses to touch a file it can't parse (broken JSON or TOML aborts with a clear message)

No telemetry, Node 18.17+. Codex TOML updates use @decimalturn/toml-patch to preserve comments and unrelated settings.

Supported clients

| Client | Global config written | |---|---| | claude-code | ~/.claude.json (user scope — every project and session) | | claude-desktop | claude_desktop_config.json (per-OS path) — bridges through mcp-remote | | codex | ~/.codex/config.toml (or $CODEX_HOME/config.toml; --project for ./.codex/config.toml) | | cursor | ~/.cursor/mcp.json (--project for ./.cursor/mcp.json) | | windsurf | ~/.codeium/windsurf/mcp_config.json | | vscode | user-profile mcp.json (--project for ./.vscode/mcp.json) | | opencode | ~/.config/opencode/config.json | | cline | cline_mcp_settings.json (stock VS Code global storage, per-OS path) | | roo-code | mcp_settings.json in VS Code global storage (--project for ./.roo/mcp.json) | | continue | ~/.continue/mcpServers/mergesafe.yaml (--project for the project copy) |

Not covered: Zed (its settings.json is JSONC with comments — a rewrite would destroy them; configure manually). Gemini CLI: use its built-in command: gemini mcp add --transport http mergesafe https://mcp.mergesafe.io/mcp -H "Authorization: Bearer msk_…"

Codex

npx @mergesafe-io/connect@latest codex --key msk_your_api_key

The official Codex MCP documentation specifies ~/.codex/config.toml for the shared user configuration and .codex/config.toml for trusted projects. If CODEX_HOME is set, the user configuration is written to $CODEX_HOME/config.toml, following the Codex configuration documentation. The CLI, desktop app, and IDE extension share this configuration.

The installer adds a Streamable HTTP connection with your API key:

[mcp_servers.mergesafe]
url = "https://mcp.mergesafe.io/mcp"
http_headers = { Authorization = "Bearer msk_your_api_key" }

Existing Codex settings, comments, and other MCP servers are preserved. Restart Codex or reload the IDE extension, then check /mcp. To install only in a trusted project:

npx @mergesafe-io/connect@latest codex --project --key msk_your_api_key

To remove only MergeSafe from the Codex user configuration:

npx @mergesafe-io/connect@latest codex --uninstall

Options

| Flag | Effect | |---|---| | --key <msk_…> | Your MergeSafe API key (from app.mergesafe.io → Settings). Prompted if omitted. | | --project | Write the project-local config instead of the global one (codex, cursor, vscode, roo-code, continue — needs an explicit client) | | --dry-run | Print the target paths and resulting files without writing | | --uninstall | Remove the mergesafe entry (no client = every detected client) | | --help | Usage |

Development

npm ci
npm test           # node --test
node bin/mergesafe-connect.js --key msk_x --dry-run          # auto-detect
node bin/mergesafe-connect.js cursor --key msk_x --dry-run   # single client

Publishing

npm publish --access public