@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: MCP Task Assistant

Quickstart

The recommended entrypoint is the complete setup wizard. It prepares the persistent daemon, detects Claude Code and Codex, connects the agents you select, and offers existing MCP servers and skills as a separate reviewed import.

This README tracks the 0.9.0 stable release, matching the package version pinned by the bundled plugin. Unqualified npm installs resolve the latest dist-tag; the examples below remain exact-versioned for reproducibility.

The CLI and UI prefer the ratel-local plugin when linking because it bundles the gateway and agent skills. Stable builds use the Ratel marketplace from the repository's default main branch. Prerelease builds alone pin the same marketplace identity to their immutable matching release tag: Codex uses --ref, while Claude Code uses the equivalent owner/repo@ref source. Stable 0.9.0 therefore carries no RC branch or tag override.

If an agent already has the plugin, link reconciles that marketplace channel and reinstalls the plugin. It verifies that an RC tag exists before changing a working installation and attempts to restore the stable plugin if an RC switch fails after removal. When stable is restored, the command preserves that connection but reports the RC setup as failed rather than claiming the requested channel is active. If no usable plugin remains, a new link uses the reviewed explicit MCP gateway fallback; a failed existing-plugin reconciliation stops with an error. Importing still recognizes an enabled plugin as an existing Ratel connection and does not add a second gateway. 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.

Complete interactive onboarding

1. Install the CLI

Node.js 20.6 or newer is required.

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

2. Run setup

ratel-local setup

The wizard:

• installs, upgrades, or starts the per-user daemon;

• detects Claude Code and Codex and asks which agents to connect;

• installs the Ratel Local plugin for each selected agent, using the reviewed explicit MCP connector only if plugin installation fails;

• separately offers to preview MCP servers and skills from selected agents;

• asks for confirmation before committing an import and backs up changed configuration.

Re-running setup is safe. A matching daemon is reported as a no-op, while existing plugin links are checked against the package's stable or prerelease marketplace channel.

If you do not have a global installation, run the release-pinned package:

npx -y @ratel-ai/ratel-local@0.9.0 setup

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.

Safe automation

Plain --yes retains the old safe behavior and changes only the daemon:

ratel-local setup --yes
ratel-local setup --daemon-only --yes

Agent changes require explicit selection. Repeat --agent, or use auto to connect every detected supported agent:

ratel-local setup --yes --agent claude-code --agent codex
ratel-local setup --yes --agent auto

Automated setup never imports native MCP servers or skills. Use the explicit expert command when migration is intended:

ratel-local import --yes --agent claude-code
ratel-local import --yes --agent codex

--port N selects the first-install daemon port. --daemon-only cannot be combined with --agent.

Expert commands

The lower-level workflows remain available for targeted repair, scripting, and debugging:

# Daemon lifecycle
ratel-local daemon install
ratel-local daemon start
ratel-local daemon status

# Connect without importing native entries
ratel-local link --agent claude-code
ratel-local link --agent codex

# Preview and confirm one agent migration
ratel-local import --agent claude-code
ratel-local import --agent codex

daemon start is idempotent: when the service is already healthy it leaves the daemon and active MCP sessions running. During a slow cold start, the connector waits for the daemon handshake and then exposes the complete catalog. Bootstrap tools appear only after attachment actually fails or a live connection is later lost; they check status before recovery and can safely attach to the running service. Set RATEL_FEATURE_CONNECTOR_RECOVERY=1 on connector processes to opt into bounded automatic reattachment after later daemon interruptions; this rollout flag is off by default.

Add new upstreams directly after onboarding:

ratel-local mcp add --scope user context7 -- npx -y @upstash/context7-mcp
ratel-local mcp list

Opt-in semantic and hybrid retrieval

BM25 remains the model-free default. The 0.7.0 feature line adds scoped semantic and hybrid retrieval with explicit model preflight:

ratel-local retrieval status
ratel-local retrieval configure --scope project --method hybrid --source built-in
ratel-local retrieval prepare --scope project

Reconnect the affected agent after changing retrieval so it acquires the new immutable gateway generation. See the retrieval configuration and preflight guide for local, Hugging Face, Ollama, and OpenAI-compatible embedding sources plus privacy and memory guidance.

Connect a Ratel Cloud account

Cloud skill-catalog credentials are stored as named profiles in ~/.ratel/cloud.json, readable only by you and never inside a repository:

ratel-local cloud add personal   # masked prompt for the key; needs a terminal
ratel-local cloud list           # stored profiles, and which one applies here
ratel-local cloud status         # this directory's resolved profile and state

Create a key at https://cloud.ratel.sh/settings. The first profile you store becomes the default, so a single account needs nothing further. To take one project's skills from a different account:

ratel-local cloud use acme --scope project

That writes cloud.profile into the project config /path/to/project/.ratel/config.json, the file stores a profile name (never a key), so it stays safe to commit and your team inherits the binding by cloning. Reconnect the agent afterwards.

Check a stored key with ratel-local cloud test <profile> (reachability and authorization are reported separately). Remove one with ratel-local cloud remove <profile>; the command refuses while this directory's user/project/local configs still select it unless you pass --force. For a machine-local switch that is not committed, use ratel-local cloud use <profile> --scope local.

Telemetry is separate and keeps its own single key in ~/.ratel/cloud-traces.json or in RATEL_API_KEY: an agent's exporter is configured once per machine, so traces and logs go to one Cloud project regardless of cloud.profile.

Experimental Cloud telemetry

Native Claude Code and Codex telemetry relay plus Ratel runtime trace export ship dark. Enable the daemon-wide feature explicitly before configuring a native exporter:

# New installation
RATEL_FEATURE_CLOUD_TELEMETRY=1 ratel-local setup

# Existing installed daemon
RATEL_FEATURE_CLOUD_TELEMETRY=1 ratel-local daemon restart

# Disable
RATEL_FEATURE_CLOUD_TELEMETRY=0 ratel-local daemon restart

ratel-local traces status

Only the exact value 1 enables a daemon feature flag; any other value disables it. Flags are persisted into the installed launchd or systemd service, and a flag you leave out of the environment keeps whatever the service already says. See the Cloud OTLP relay and native exporter setup contract for privacy levels, precedence, failure behavior, and rollback instructions.

Experimental Cloud skill catalog

A project's skills published to Ratel Cloud can join the locally resolved skill set, served through the same gateway and the same capability search as local ones. Off by default:

# New installation
RATEL_FEATURE_CLOUD_CATALOG=1 ratel-local setup

# Existing installed daemon
RATEL_FEATURE_CLOUD_CATALOG=1 ratel-local daemon restart

# Disable
RATEL_FEATURE_CLOUD_CATALOG=0 ratel-local daemon restart

The flag follows the same semantics as Cloud telemetry above, and the two are independent.

The catalog pulls with the Cloud profile this directory resolves to, stored in ~/.ratel/cloud.json and read on every pull, so a rotated key applies without a restart.

A local skill with the same id wins, and the shadowed Cloud one is reported as a warning in the daemon UI. An unreachable or stale catalog is a warning too, never a failed context resolve.

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. Repository contributors can also read the retrieval configuration and preflight guide and the Cloud OTLP relay and native exporter setup contract.

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.