Introduction
Ratel Local: MCP Gateway that fronts Claude Code / Codex / Cursor with capability search.
Ratel Local is one MCP server for your whole tool estate. It connects to your upstream MCP servers and exposes a small, searchable capability surface to Claude Code, Codex, Cursor, or any other MCP client.
Your client sees search_capabilities and invoke_tool, plus get_skill_content when
skills are configured and auth for authorizing OAuth upstreams.
Upstream tool schemas stay out of context until a search makes them relevant.
Ratel Local is the gateway host in Ratel's architecture. The capability contracts belong to progressive disclosure; Ratel Local owns host setup, upstream configuration, authentication, and operation.
Start with setup
ratel-local setup prepares the background daemon, detects Claude Code and Codex,
connects the agents you select, and separately offers a reviewed import of existing
MCP servers and skills.
Quickstart
Install Ratel Local, run setup, and verify capability search.
Cursor
Add Ratel Local to Cursor manually through its standard mcp.json configuration.
MCP servers
Configure scopes, add upstreams, and verify the running gateway.
Daemon
Understand the background service, project gateways, lifecycle, and upgrades.
Retrieval
Keep BM25 or opt into semantic and hybrid search for one scope.
Import or link
Move native MCP entries into Ratel Local or connect a host without migrating them.
Browser UI
Manage local configuration in a loopback-only browser app.
Managing skills
Register skills by scope and wire the prompt-time preload hook.
OAuth upstreams
Authorize remote servers, inspect status, and recover from a 401.
Statusline & local telemetry
Inspect local events and show estimated context savings in Claude Code.
Experimental Cloud telemetry
Review the default-off feature gate before enabling native trace export.
Embed as a library
Build and serve a Ratel Local gateway from your own Node process.
Troubleshooting
Recover from host, upstream, authentication, scope, and telemetry failures.
Ratel Local or an SDK?
Use Ratel Local when your tools already live behind MCP servers and you do not own the agent loop. Use a Ratel SDK when you want in-process catalog control, local function tools, or framework wiring. Both expose the same capability-tool contract.
Ratel Local ships as
@ratel-ai/ratel-local. The CLI
binary is ratel-local and requires Node.js 20.6 or newer.