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.

For first-time onboarding, run ratel-local setup. It prepares the daemon, links the agents you select, then offers import as a separate reviewed step.

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

ratel-local import --agent claude-code imports selected Claude Code MCP servers and native skills into matching Ratel scopes.

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

ratel-local import
ratel-local import --agent claude-code
ratel-local import --agent codex
ratel-local 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.

If the source agent is not linked, the wizard first offers to link Ratel Local, continue without linking, or cancel. Linking installs the agent plugin when possible; only a failed plugin installation falls back to an explicit MCP gateway entry.

The import then has these stages:

1. Select native MCP entries and move them into matching Ratel scopes.
2. Select native skills to manage as invoke-only.
3. Remove the selected MCP entries from the source agent.

The final import commit asks for confirmation. Claude Code then offers a separate, skippable statusline installation step.

If you continue without linking, imported MCPs and skills are not usable from that source agent until you run link later.

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-local 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"]
    }
  }
}

When plugin installation is unavailable, linking or importing with link enabled writes one reviewed fallback connector entry. The generated command and absolute path depend on your global installation and host scope.

 {
   "mcpServers": {
-    "context7": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
+    "ratel-local": {
+      "type": "stdio",
+      "command": "/absolute/path/to/ratel-local",
+      "args": ["connect", "--agent-host", "claude-code", "--link-scope", "user"]
     }
   }
 }

-[mcp_servers.context7]
-command = "npx"
-args = ["-y", "@upstash/context7-mcp"]
+[mcp_servers.ratel-local]
+command = "/absolute/path/to/ratel-local"
+args = ["connect", "--agent-host", "codex", "--link-scope", "user"]
+enabled = true

Link without migrating

ratel-local link --agent claude-code
ratel-local link --agent codex

link installs or reconciles the stable Ratel Local plugin first. A disabled Codex plugin MCP server is re-enabled. If a new plugin installation fails, link writes a ratel-local fallback connector entry. A failed reconciliation of an existing plugin stops instead of silently replacing a working connection. Native MCP entries are not moved or removed.

Stable releases follow the marketplace's default main branch. Do not add a branch, tag, or --ref override to a stable link.

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-local

codex mcp get ratel-local --json

Backups and rollback

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

Scoped mutations are revision-checked and journaled. A failed multi-file commit restores the files written by that commit when restoration is supported.

ratel-local 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