Import or link

Use import to move existing host servers behind Ratel Local. Use link when Ratel is already configured and you only need to connect the host.

Supported hosts and files

Import and link have native adapters for Claude Code and Codex only.

Without --agent, auto-detection chooses the first supported host with native entries: Claude Code, then Codex. Pass --agent when both are configured. Cursor and other MCP clients use manual host configuration.

Import native servers

Run the wizard from the project where you use the native servers.

ratel-mcp mcp import
ratel-mcp mcp import --agent claude-code
ratel-mcp mcp import --agent codex
ratel-mcp mcp import --agent codex --dry-run

--dry-run prints planned writes and does not change files. The interactive flow may still start upstreams to read their instructions before it renders the plan. --yes selects every candidate, skips those probes and prompts, and keeps existing Ratel entries when names conflict.

The wizard has two write stages:

1. Select native entries and move them into the matching Ratel scopes.
2. Replace those native entries with a ratel-mcp entry in each affected host scope.

Each stage asks for confirmation.

If you decline stage two, the new Ratel entries stay in place and the host remains unchanged. Run mcp link later to connect it.

Entries you do not select stay native. Claude Code scopes are preserved. Codex preserves user and project scopes; its adapter has no local scope.

When the same name appears at multiple scopes, the most specific candidate wins: local, then project, then user.

Resolve name conflicts

Choose how imports handle a server name that already exists in Ratel.

ratel-mcp mcp import --agent codex \
  --conflict-strategy add-missing-only

replace-selected is interactive. It cannot be combined with --yes or --dry-run.

Before and after

Stage one copies the selected entry into the matching Ratel scope:

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Stage two removes that native entry and adds one gateway entry. The generated command and absolute paths depend on your installation and scope chain.

 {
   "mcpServers": {
-    "context7": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
+    "ratel-mcp": {
+      "type": "stdio",
+      "command": "/absolute/path/to/ratel-mcp",
+      "args": ["serve", "--config", "/Users/you/.ratel/config.json"]
     }
   }
 }

-[mcp_servers.context7]
-command = "npx"
-args = ["-y", "@upstash/context7-mcp"]
+[mcp_servers.ratel-mcp]
+command = "/absolute/path/to/ratel-mcp"
+args = ["serve", "--config", "/Users/you/.ratel/config.json"]
+enabled = true

Link without migrating

ratel-mcp mcp link --agent claude-code
ratel-mcp mcp link --agent codex

link writes a ratel-mcp entry in each applicable host scope. Each entry receives the correct configuration chain. Native MCP entries are not moved or removed.

link supports --yes but has no dry-run mode. Use the interactive preview when you want to inspect every planned host write.

Restart the host after an import or link. Then confirm the entry:

claude mcp get ratel-mcp

codex mcp get ratel-mcp --json

Backups and rollback

add, edit, remove, import, and link snapshot every file they change under a timestamped directory in ~/.ratel/backups/ before writing.

ratel-mcp backup list
ls -1 ~/.ratel/backups

backup list prints only the creation time, action, and file count. Open the matching manifest.json to find each originalPath, hashed backupPath, and existedBefore value. An import can create separate backup sets for its Ratel and host stages.

There is no restore command. To roll back, stop the host, save the current file elsewhere, copy each required backupPath to its originalPath, and restart the host.

When existedBefore is false, no older body exists. Save the new file elsewhere, then remove it to restore the original state. A failed multi-file stage restores files it already wrote, but it does not reverse an earlier completed import stage.

Next steps