@ratel-ai/mcp-server

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.

Related MCP server: Enterprise MCP Gateway and Tool Registry

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

Confirm that ratel-local is connected or enabled, then restart Claude Code or start a new Codex session.

Start fresh with the plugin

1. Install Ratel Local

# Claude Code
claude plugin marketplace add ratel-ai/ratel-local
claude plugin install ratel-local@ratel

# Codex
codex plugin marketplace add ratel-ai/ratel-local
codex plugin add ratel-local@ratel

Reload or restart Claude Code, then start a new Codex session.

2. Add an upstream

The plugin does not install the global CLI, so use npx:

npx -y @ratel-ai/ratel-local@latest mcp add \
  --scope user context7 -- npx -y @upstash/context7-mcp

npx -y @ratel-ai/ratel-local@latest mcp list

Restart the agent after changing the configuration.

Verify capability search

Ask the agent to call Ratel Local explicitly:

Call Ratel's search_capabilities tool with:
{"query":"look up current React framework documentation","topKTools":3,"topKSkills":1}
Return the raw result.

The result should contain a tools bucket with matching upstream tools and a skills bucket. You are now using Ratel Local's on-demand capability search.

For troubleshooting and the complete setup guide, see the Ratel Local quickstart.

For configuration scopes, OAuth, skills, the local UI, telemetry, and library usage, see the Ratel Local Docs.

How it works

Ratel Local reads your layered mcpServers configuration, connects to each upstream, and registers its tools in one Ratel catalog.

Your MCP client sees capability tools instead of the full upstream catalog. search_capabilities finds relevant tools and skills, and invoke_tool runs a selected tool.

When skills are configured, get_skill_content loads their instructions.

The CLI manages upstreams, agent imports and links, OAuth, skills, backups, the browser UI, and the Claude Code statusline. The docs are the source of truth for commands and configuration.

Development

Development requires Node.js 24+ and pnpm 10+.

pnpm install
pnpm build
pnpm typecheck
pnpm lint
pnpm test

See CONTRIBUTING.md for the development workflow.

License

MIT. See LICENSE.md.