Quickstart: Claude Code & Codex
Put Ratel Local in front of an MCP setup and verify capability search in under five minutes.
Ratel Local gives Claude Code or Codex one searchable catalog instead of every tool schema from every upstream server. The fastest way to start is the plugin: install it, then add your upstreams.
If you're using Cursor, follow the manual Cursor setup. Ratel Local 0.4.0 does not provide a Cursor import or link adapter.
Start fresh with the plugin
Use this path when you want plugin-managed startup and are adding upstreams directly to Ratel.
Already have MCP servers configured?
Migrate your existing native entries into Ratel Local instead of adding them by hand. Jump to Migrate an existing MCP setup below.
Install Ratel Local from its marketplace
claude plugin marketplace add ratel-ai/ratel-local
claude plugin install ratel-mcp@ratelRun /reload-plugins in Claude Code, or restart it.
codex plugin marketplace add ratel-ai/ratel-local
codex plugin add ratel-mcp@ratelThen start a new session. Older Codex CLIs without plugin add: run codex,
enter /plugins, and install Ratel MCP from the Ratel marketplace.
The plugin starts @ratel-ai/mcp-server@latest serve --auto-config over stdio.
Add an upstream to Ratel
The plugin does not install the global CLI, so use npx for a zero-install setup:
npx -y @ratel-ai/mcp-server@0.4.0 mcp add \
--scope user context7 -- npx -y @upstash/context7-mcp
npx -y @ratel-ai/mcp-server@0.4.0 mcp listRestart the host or start a new session after changing the configuration.
The first npx launch may download packages and probe the upstream. If it stalls, see
First-run networking.
Migrate an existing MCP setup
Use this path when Claude Code or Codex already has one or more native MCP servers.
Install the Ratel Local CLI
Node.js 20 or newer is required.
npm install --global @ratel-ai/mcp-server@0.4.0
ratel-mcp --versionThe binary is ratel-mcp. The separate ratel command belongs to an older package and
does not support the Codex-aware import flow.
Import the host's MCP servers
Run the wizard from the project where you use those servers:
ratel-mcp mcp import --agent claude-coderatel-mcp mcp import --agent codexSelect the upstreams to migrate, approve the Ratel config write, then approve replacing
the selected native entries with a Ratel Local entry in each affected host scope. The
wizard preserves scopes and stores backups under ~/.ratel/backups/.
See Import or link for dry runs, conflict strategies, and manual rollback.
No native MCP servers yet?
Seed Context7 in the host, then run the import command again:
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcpcodex mcp add context7 -- npx -y @upstash/context7-mcpConfirm Ratel Local and restart
claude mcp get ratel-mcpLook for Status: ✔ Connected, then restart Claude Code.
codex mcp get ratel-mcp --jsonConfirm that the server is enabled, then start a new Codex session.
Verify search_capabilities
In either setup, ask the agent to make the capability call explicitly:
Call Ratel's search_capabilities tool with:
{"query":"look up current React framework documentation","topKTools":3,"topKSkills":1}
Return the raw result.The host should show a search_capabilities call. The raw result includes tool hits
grouped by upstream, a separate skills bucket, and each hit's complete input schema.
See Progressive disclosure for the authoritative request and response contract.
You are now using Ratel Local. The host keeps the small capability-tool contract in context; upstream schemas stay behind Ratel until a search makes them relevant.
Next steps
Manage MCP servers
Add upstreams, understand scopes, and run Ratel Local yourself.
Import or link
Compare migration, host linking, conflict handling, and rollback.
Set up Cursor
Add the gateway to Cursor through its standard mcp.json configuration.
Troubleshoot a setup
Diagnose missing tools, host restarts, authentication, and version drift.
See how Ratel Local fits
Follow a request from the host through retrieval, discovery, and invocation.
Use a Ratel SDK
Use the TypeScript or Python SDK when you own the agent loop.