Troubleshooting

Start by separating three layers: the host must start Ratel Local, Ratel Local must load the intended config chain, and each upstream must connect. A green host entry proves only the first layer.

Symptom map

Gateway absent or disconnected

Confirm Ratel's configuration, then run the same gateway manually from the project root:

ratel-mcp mcp list
ratel-mcp serve --auto-config --project-root "$PWD"

The second command occupies the terminal and writes diagnostics to stderr. Fix its first error before debugging the host. Stop it with Control-C before letting the host start its own copy.

Inspect the host-facing entry:

claude mcp get ratel-mcp

codex mcp get ratel-mcp --json

cursor-agent mcp list
cursor-agent mcp list-tools ratel-mcp

If the manual gateway starts but the host does not, compare the host's configured command, arguments, environment, and working directory with the successful terminal command.

Double registration

Ratel Local 0.4.0 can be started either by the Ratel plugin or by an explicit ratel-mcp host entry. Enabling both can launch two gateways and expose duplicate capability tools.

Keep exactly one startup path:

• Fresh setup: keep the plugin and add upstreams directly with ratel-mcp mcp add.
• Migrated setup: keep the explicit entry written by mcp import or mcp link, and disable the plugin.
• Cursor: keep one ratel-mcp entry across project and user mcp.json files.

Duplicate tools can also come from duplicate upstream entries in one Ratel config — a different fix. Identify which gateway process serves the duplicates before removing anything, then fully restart the host.

One upstream is missing

Ratel Local continues when an upstream fails. The final message ready, N upstream server(s) configured counts config entries, not successful connections.

Run the gateway manually and inspect lines before ready:

ratel-mcp serve --auto-config --project-root "$PWD" 2>ratel-startup.log

Then inspect the resolved entry:

ratel-mcp mcp get <name>

An import can preserve a host-specific transport alias or omit host-only controls. Review the converted entry after import stage one, before rewriting the host. See Import fidelity.

Authentication failures

mcp list and mcp auth --check read local token metadata; they do not call the provider. An ok row can therefore be followed by a live 401.

ratel-mcp mcp auth --check
ratel-mcp mcp auth <name>

If authorization still fails:

1. Verify clientId, clientSecret, OAuth scope, and fixed callback port against the provider configuration.
2. If dynamic client registration is unsupported, supply the complete static-client entry with mcp edit --entry-json, or re-add the upstream.
3. Complete the browser callback within five minutes.
4. Restart the gateway and host so the upstream reconnects with the new token set.

A failed startup refresh clears the unusable stored token. An access-token-only token file also needs a new authorization flow because Ratel cannot refresh it. See OAuth upstreams for token storage and 401 recovery.

Wrong project root or config scope

Ratel loads scopes in this order, with later entries replacing matching names:

~/.ratel/config.json
<projectRoot>/.ratel/config.json
<projectRoot>/.ratel/config.local.json

Project discovery prefers the nearest ancestor with pnpm-workspace.yaml; otherwise it looks for .git, .mcp.json, or package.json. For serve --auto-config, an explicit --project-root wins, then RATEL_PROJECT_ROOT, CLAUDE_PROJECT_DIR, and the process working directory.

Run from the intended project and read the startup lines listing the root and config paths:

ratel-mcp serve --auto-config --project-root /absolute/path/to/project

Use absolute paths in host entries when workspace variables are unavailable. A project or local CLI mutation also depends on discovery, so run mcp add, edit, or remove from inside that project.

First-run networking

The first npx -y @ratel-ai/mcp-server@0.4.0 ... can download the package. mcp add also probes the new upstream for its description unless you pass one or use --no-fetch-description.

Separate package access from upstream startup:

npm view @ratel-ai/mcp-server@0.4.0 version
npx -y @ratel-ai/mcp-server@0.4.0 --version

If either command fails, fix npm registry, proxy, DNS, or certificate access in the same environment the host inherits. If those pass but mcp add stalls, run the upstream command directly. Use --no-fetch-description only when you intentionally want to defer the connection and initial OAuth probe.

For managed hosts, a first launch may need a restart after the download completes. Pin the same package version in every manual host entry to avoid fetching different releases.

Version mismatch

These pages document @ratel-ai/mcp-server 0.4.0. Find every binary that can win on PATH and compare it with any npx or plugin-managed command in the host config:

which -a ratel-mcp
ratel-mcp --version
npx -y @ratel-ai/mcp-server@0.4.0 --version

If behavior differs, choose one installation, update the host entry to that command, and restart. Do not combine a plugin that launches its own package with an imported explicit entry. When debugging, keep @ratel-ai/mcp-server@0.4.0 pinned rather than mixing a global binary, @latest, and 0.4.0.

Restart requirements

Most hosts cache MCP connections and their tool lists for a session. Restart after:

• importing, linking, or manually changing a host MCP entry;
• adding, editing, removing, or reauthorizing an upstream;
• changing Ratel project scope, skills directories, or package version.

Re-run an explicit search_capabilities call after restart. Host connection status alone does not prove every upstream joined the catalog.

Recovery and deeper logs

• Import or link problem: inspect ~/.ratel/backups/<timestamp>/manifest.json and follow the manual rollback procedure. There is no restore command.
• Statusline says it is waiting: align the gateway working directory with Claude Code's project directory; see Statusline & telemetry.
• OAuth or invocation failure: inspect the local JSONL event stream (event meanings in telemetry semantics), taking care not to share secrets or private query data.

FAQ

Do I need both the plugin and the CLI?

No — they are alternative startup paths. The plugin starts the gateway itself and does not install the global CLI; run configuration commands with npx -y @ratel-ai/mcp-server@0.4.0. Install the global CLI for the migration path, and never keep both startup paths registered (see Double registration).

Can native MCP servers stay alongside Ratel Local?

Yes. Entries you do not migrate keep working natively; their schemas simply stay in the host's context without capability search. Just never leave the same server in both places — that exposes duplicate tool schemas (Import or link).

How do I update Ratel Local?

There is no self-update command. Reinstall the global package at the new version — imported host entries run that binary directly — and update the version pinned in manual host entries and npx commands to match; the plugin launches @latest, so it tracks releases on its own. Keep one version everywhere and restart the host (Version mismatch).

Where does Ratel Local store its data?

User-level state — configuration, managed skills, OAuth tokens, telemetry, and backups — lives under ~/.ratel/; project and local scopes live in <projectRoot>/.ratel/. The gateway runs on your machine and its telemetry sink writes local JSONL only; traffic still flows to the upstream servers you configure. See Retention and privacy.

Can I share one configuration across hosts and projects?

Yes. Every documented startup path loads user scope ~/.ratel/config.json first — the plugin and the Cursor entry through --auto-config, import and link entries through their generated --config chain — so Claude Code, Codex, and Cursor see the same user-scope upstreams. Add per-project servers at project or local scope; later scopes override earlier ones by name (Configuration scopes).

Is there a restore command?

No. ratel-mcp backup list shows the snapshots under ~/.ratel/backups/; rolling back is manual. Copy each backupPath in the set's manifest.json over its originalPath, and delete files whose existedBefore is false. Follow Backups and rollback.

How do I remove Ratel Local completely?

Reverse the moves first: ratel-mcp skill deactivate, ratel-mcp skill uninstall-hook, and ratel-mcp statusline uninstall. Then remove the ratel-mcp host entry or plugin, and restore any migrated native servers from backups (rollback). Finally delete ~/.ratel/ and uninstall the global npm package if you installed one.

Next steps