Skip to main content
Most MCP problems fall into one of four groups:
  • Connection: the client can’t reach Earnie, or Earnie refuses the request before it checks the key.
  • Authentication: Earnie rejects the key.
  • Configuration: the client’s configuration doesn’t match what the Earnie CLI set up.
  • Tools: a tool refuses a request, or isn’t there.
Each section quotes the messages Earnie and the Earnie CLI give, so you can search this page for the text you see.

​
Start with Doctor

If you set up with the Earnie CLI, run doctor first. It checks the setup without changing anything:
Doctor reports:
  • whether the CLI is compatible with your Earnie
  • whether your key is valid, and whether it came from the stored login (stored) or EARNIE_API_KEY
  • the project it would use
  • each client’s configuration, policy block, and hooks
  • whether the agent can see each Earnie tool, and the reason for any it can’t
For each problem, doctor suggests a fix, usually an earnie mcp setup --client <client> command to run. Doctor exits 0 when everything is healthy and 9 when it finds a problem. To check only your user-level client configuration, outside a repository and without a project, run:
If you didn’t set up with the CLI, ask the agent to call platform_health_ping, as in Step 4, and match what you see against the sections below.

​
Connection Problems

​
Authentication Problems

Earnie rejects a missing or invalid key with HTTP 401. The response gives a code and a message: If a client keeps retrying with a bad key, Earnie starts answering 429, “too many authentication attempts”, to every key attempt from that address. Fix the key first, then wait for the number of seconds in the Retry-After header. If doctor says “no API key; set EARNIE_API_KEY or run earnie auth login”, the CLI itself has no key. Run earnie auth login.
Using Cursor’s install link? Its configuration reads the key from an environment variable named EARNIE_API_KEY. If that variable isn’t set in the environment Cursor starts from, Cursor sends no key, and Earnie answers unauthenticated. Set the variable, then restart Cursor.

​
Configuration Problems

Doctor reports these messages when a client’s configuration doesn’t match what the CLI set up: Setup can also warn you about a conflict:
Windows and WSL use different home directories. The Windows build of earnie, including when you run it from Git Bash, writes to %USERPROFILE%, for example %USERPROFILE%\.claude.json. A WSL build writes to your Linux home directory, which Claude Code and VS Code on Windows don’t read. If setup can’t find a client you expect, check which earnie binary ran.

​
Tool Problems

​
Permissions and Projects

​
Code Reviews

These come from earnie_review_code:

​
Other Tools

​
Still Stuck?

​
What’s Next

With your agent connected, Earnie records every review the agent runs as a Self-check. See Self-checks to learn how to read one.