Ratel Local

Ratel Local gives coding agents one searchable catalog instead of every tool schema from every upstream MCP server. Tools and skill instructions enter context only when the agent needs them, with no agent-code changes.

It ships as the npm package @ratel-ai/ratel-local and the ratel-local CLI. The package also exposes library APIs for serving a Ratel ToolCatalog over MCP.

Why Ratel Local

• Smaller context: upstream tool schemas and skill bodies stay out of the prompt until they are relevant.
• Better tool selection: capability search gives the model a focused set of choices. See the benchmarks.
• Fits existing setups: bring the MCP servers you already use in Claude Code, Codex, Cursor, and other MCP clients.
• Runs locally: Ratel Local runs on your machine; configuration and upstream credentials are stored locally.

Quickstart

Choose the setup that matches where you are starting:

• Migrate existing MCP servers: install the CLI and import the servers already configured in Claude Code or Codex.
• Start fresh with the plugin: let the plugin start Ratel Local, then add upstreams directly to Ratel Local configuration.

The CLI and UI prefer the ratel-local plugin when linking because it bundles the gateway and agent skills. If plugin installation fails, Ratel Local reports the failure and applies the reviewed explicit MCP gateway fallback instead. An enabled plugin is recognized as an existing Ratel connection, so importing does not add a second gateway and link becomes a no-op. If the Codex plugin is enabled but its bundled Ratel MCP server is disabled, link re-enables that server. Agent Setup offers Fix duplicate installation when both the plugin and an explicit Ratel MCP entry are present, and Switch to plugin for MCP-only installations. Both actions preserve the existing MCP connection unless plugin installation succeeds, and only recognized Ratel entries are removed.

Migrate an existing MCP setup

1. Install the CLI

Node.js 20 or newer is required.

npm install --global @ratel-ai/ratel-local
ratel-local --version

2. Import the agent's MCP servers

Run the command for your agent from the project where you use those servers:

# Claude Code
ratel-local import --agent claude-code

# Codex
ratel-local import --agent codex

The CLI and UI use the same import sequence. If the source agent is not linked, the first step offers to link and continue, continue without linking, or cancel. The confirmed import writes selected entries to Ratel, removes those MCP entries from the source agent, and marks selected native skills invoke-only. Skipping the link is useful when importing for another linked agent, but the imported MCPs and skills are no longer directly usable from the unlinked source agent. The wizard preserves MCP scopes and backs up every changed MCP or agent config file. Skill management is reversible: use Stop managing in the UI or ratel-local skill deactivate to remove Ratel's link and restore its metadata changes.

Claude Code then offers a separate, skippable Ratel statusline step. Linking installs the agent plugin when possible and otherwise writes the explicit Ratel gateway fallback. Install or reinstall the statusline manually with ratel-local statusline install.

If your upstreams are already in Ratel Local configuration, link installs the Ratel plugin without importing or removing native entries. If plugin installation fails, it clearly reports the failure before writing the reviewed MCP fallback:

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

Native entries remain directly exposed, so their schemas still enter the agent's context without capability search.

3. Confirm Ratel Local and restart

# Claude Code
claude mcp get ratel-local

# Codex
codex mcp get ratel-local --json