Frenchie
MCP onlineLog in

docs → troubleshooting

Troubleshooting

Paste the exact error text you saw into Cmd-F. Every entry leads with the verbatim symptom so search engines (and you) can jump straight to the fix.

MCP server does not exist: frenchie

Affects: Cursor

Reproduced in dogfood: after a fresh install, Cursor surfaces this error even though .cursor/mcp.json was written correctly. Cursor's official docs say new MCP servers are enabled by default, but in practice a newly-registered server can land in a disabled state and needs a manual toggle before the agent can call it.

Fix:

  1. Open Cursor Settings (Cmd+, on macOS, Ctrl+, elsewhere)
  2. Search for "MCP"
  3. Find the frenchie row and toggle it on
  4. Restart Cursor

A full app restart is required — reloading the window alone doesn't always pick up the toggle.

exec: "npx": executable file not found in $PATH

Affects: Antigravity, Claude Desktop, Windsurf, Zed (any GUI-launched agent)

GUI apps on macOS don't inherit your shell's PATH. When the MCP config says "command": "npx", a GUI-launched agent can't find npx and the stdio server never starts.

Fix (0.3.0+): re-run the installer.

npx @lab94/frenchie@latest install --api-key fr_your_key_here

0.3.0 writes the absolute path to npx into command plus a scoped PATH into env so both layers of the failure resolve.

Fix (hand-written configs):

{
  "mcpServers": {
    "frenchie": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "@lab94/frenchie", "mcp"],
      "env": {
        "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin",
        "FRENCHIE_API_KEY": "fr_..."
      }
    }
  }
}

Get the absolute path with which npx (or where npx on Windows). See also: env: node: No such file or directory.

env: node: No such file or directory

Affects: Antigravity, any GUI-launched agent

Layer B of the PATH gap. Even when command points at an absolute npx, the #!/usr/bin/env node shebang inside npx still tries to resolve node on PATH — and the GUI-inherited PATH is usually empty.

Fix: same as the npx-not-found case — 0.3.0's installer writes a PATH into the MCP config's env block, which resolves both layers at once.

Agent still uploads + curl PUTs files after upgrade

Affects: Claude Code, Cursor, Codex

An old HTTP Frenchie entry in user or local scope is shadowing the new project stdio entry. Claude Code precedence is local > project > user, so a leftover HTTP entry in the higher scope wins.

Fix (Claude Code):

claude mcp list                      # check which scope has frenchie
claude mcp remove frenchie -s local  # or -s user / -s project

Fix (Cursor): edit ~/.cursor/mcp.json, remove the frenchie block that has a url field.

Fix (Codex): edit ~/.codex/config.toml, remove any [mcp_servers.frenchie] block whose body sets url = "..." rather than command = "npx".

Then re-run npx @lab94/frenchie install --api-key fr_... and restart your agent. The installer in 0.3.0 will also probe these locations proactively and warn you before it writes over anything.

Auth unsupported label in the Codex Desktop MCP panel

Affects: Codex Desktop

Not an error. Codex Desktop's MCP panel shows frenchie — Auth unsupported — Enabled because it has no UI control for stdio env-var auth. It labels every env-authenticated server that way.

The server still launches with FRENCHIE_API_KEY in its env (we wrote it into ~/.codex/config.toml during install). Invoke via @frenchie, /frenchie, or natural language — all three work.

npx @lab94/frenchie mcp --help

Affects: VS Code Copilot (preflight), CI health checks

Pre-0.3.0, mcp --help unconditionally booted the stdio server and waited for JSON-RPC. Agents that preflight with --help (observed: VS Code Copilot) read this as a hang and refuse to register the server.

Fix: upgrade to 0.3.0 or later. The mcp subcommand now short-circuits on --help, --version, and --selftest before touching the bundled server.

npm install -g @lab94/frenchie@latest

Verify locally: npx @lab94/frenchie mcp --selftest should print a PASS line and exit 0.

Install ran but the agent behaves as if nothing changed

Affects: All Tier A agents

You forgot --api-key. Without it, the installer copies skill files but skips the MCP config write, so your agent still has no idea how to reach Frenchie.

Fix:

npx @lab94/frenchie install --agent <name> --api-key fr_your_key_here

You can also set FRENCHIE_API_KEY in your shell and re-run install without the flag — either works.

UnrecognizedClientException: The security token included in the request is invalid

Affects: VS Code Copilot (during MCP preflight)

Not a Frenchie or npm error. This is an AWS STS message. In the dogfood case that surfaced it, VS Code Copilot's own AWS-hosted backend had an expired STS token and misattributed the failure to our package.

Confirm it's not us:

  1. Check your ~/.npmrc — if there's no CodeArtifact / private registry config, the error can't be coming from our package fetch.
  2. Run npx @lab94/frenchie mcp --selftest in a regular terminal. If it passes, the preflight path from your agent is the problem, not our binary.
  3. Retry the preflight in a fresh Copilot session. STS tokens refresh on a new session.

/ocr doesn't work in my agent

Affects: Any agent that&apos;s not Claude Code

Expected. /ocr, /transcribe, /generate-image, and /frenchie-status are Claude Code-only slash commands (they come from the .claude/commands/*.md files we copy during install). Other agents don't support project-defined slash commands.

Use per your agent:

  • Codex (Desktop / CLI / IDE): @frenchie, /frenchie, or natural language
  • Antigravity: /frenchie <file> (Antigravity invokes MCP servers by name)
  • VS Code Copilot: /frenchie <file> once the server is registered
  • Cursor / Claude Desktop / Windsurf: natural language ("Use Frenchie to OCR X")

Full details per agent in the invocation matrix.

Still stuck?

Email support@getfrenchie.dev with the exact command you ran and the full error output. We'll either add a new entry here or find you a fix directly.

More