Troubleshooting Earnie MCP - SCANOSS documentation

Most MCP problems fall into four groups: the client can’t reach Earnie, Earnie rejects the key, the client’s configuration is out of step, or a tool refuses a request. This page covers each, using the messages Earnie actually returns.

Start with Doctor

If you set up with the Earnie CLI, run doctor first. It checks the installation without changing anything:

earnie mcp doctor

Doctor reports:

whether the CLI is compatible with your Earnie deployment
whether your key is valid, and where it came from (the stored login or EARNIE_API_KEY)
the project it would use
each Earnie tool’s visibility, and why a tool is missing if it is

It ends with a suggested fix, such as the earnie mcp setup command to run. To check only the connection and key, without a repository, run earnie mcp doctor --global.

Connection Problems

Symptom	Cause and Fix
The client can’t connect at all.	Check the MCP address is your Earnie address followed by `/mcp/v1`, and that your machine can reach it. See Step 2.
`405` — “the MCP endpoint accepts POST only”	Something sent a `GET` or `DELETE` request, often a browser or a client configured for another transport. Configure the client for HTTP (streamable HTTP), not SSE.
`406` — “Accept must include application/json”	The client asked for a streamed response only. Earnie’s MCP server always answers with JSON and never streams.
`403` — `origin_not_allowed`	The request came from a web page on another site. Ask your administrator to add that origin to `EARNIE_MCP_ALLOWED_ORIGINS`. Desktop and terminal clients aren’t affected.
`413` — `payload_too_large`	The request was over 8 MiB. Review fewer files at once.
Claude.ai or ChatGPT can’t connect.	They connect from the vendor’s cloud, so your Earnie must be reachable from the public internet, and they expect OAuth. See Claude.ai and ChatGPT.

Authentication Problems

Earnie rejects a missing or invalid key with HTTP 401. The response names the reason:

Code	Message	Fix
`unauthenticated`	”authentication required”	The client sent no key. Check the `Authorization: Bearer <key>` header is configured, including the space after `Bearer`.
`invalid_key`	”API key invalid”	The key is wrong or incomplete. Copy it again, or generate a new one.
`key_revoked`	”API key has been revoked”	Generate a new key, and update the client.
`key_expired`	”API key has expired”	Generate a new key, and update the client. See Expiry.

If a client keeps retrying with a bad key, Earnie starts answering 429 — “too many authentication attempts”. Fix the key, then wait for the time given in the Retry-After header.

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. Set the variable, then restart Cursor.

Configuration Problems

Doctor reports these when it finds the client’s configuration out of step with the CLI:

Doctor Says	Fix
”configured MCP URL does not match the resolved API URL”	The client points at a different Earnie deployment. Run `earnie mcp setup` again.
”native config credential does not match the current CLI credential”	The client holds an old key. Run `earnie auth login` or `earnie mcp setup`, then restart the client.
”native config still references EARNIE_API_KEY; Claude Code and Cursor cannot read the CLI credential store”	Run `earnie auth login` or `earnie mcp setup`, then restart the client.
”repository MCP config still has an Earnie server; identity belongs in the user-level client”	An older setup left the connection in the repository. Run `earnie mcp setup` to move it to your user-level configuration.
”Cursor has Earnie in both repository and global configuration”	Cursor doesn’t define which one wins. Run `earnie mcp setup` to remove the repository copy.
”managed block revision does not match the server”	The project’s policies have changed. Run `earnie mcp setup` to refresh the policy block.
”Codex project hooks are installed but not trusted”	Inside Codex, run `/hooks` and approve Earnie’s hook definitions.

Windows and WSL use different home directories. The Windows build of earnie, including when run 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

Symptom or Message	Cause and Fix
A tool is missing from the agent’s list.	The key lacks that tool’s permission. Doctor shows it as “hidden because this key is missing” the permission. Generate a key with the permission. See Step 1.
”this API key lacks the … scope, which … requires”	Same cause: the agent called a tool the key can’t use. Ask an organisation Admin for a key with that permission.
”This tool needs a Project. Pass `project` with one of: …”	The agent didn’t name a project, and there’s no default. Name the project in your request, or set a default project.
”This API key is not authorized for project … It can act on: …”	The project doesn’t exist, or the key can’t reach it. Earnie gives the same answer for both. Use a project from the list, or a key that covers it.
”This API key can act on no Project”	The key reaches no active project. Generate a key with the projects you need.
”Rate limit: this API key may start … self-checks a minute”	The agent started too many code reviews. Wait the time given, then retry. The default limit is 30 a minute.
”This change is too large to review in one call”	Over 200 files, 512 KiB in one file, or 1 MiB in total. Use `earnie scan diff` from the Earnie CLI.
”Project … is archived, so no new check can run in it”	Restore the project first. See Archiving, Restoring, and Resetting.
”Earnie cannot review this change for this organization”	No scanner that could review the change is enabled for your organisation. Ask an administrator which scanners are enabled.
A review returns `status: "running"` instead of a verdict.	This isn’t an error. The review took longer than the wait budget. The agent should call `earnie_review_code` again with only the `selfcheck_id`.
”No self-check … in project …”	The Self-check ID is wrong, or the check was purged. Self-checks are kept for 30 days.
”There is no SBOM Snapshot for … yet”	`earnie_export_cbom` only reads existing snapshots. Generate a snapshot first.
”limit must be between 1 and 200”	The agent asked for too many rows. Ask for fewer.
`earnie_review_code` refuses a session: “This credential cannot start a self-check”	The client signed in as a person instead of using an API key. Configure the client with an API key.

Still Stuck?

Check the key’s permissions and projects on Settings → API keys. See Managing Keys.
Check the CLI’s own reference for setup, doctor, and uninstall.

What’s Next

With your agent connected, every review it runs is recorded as a Self-check. See Self-Checks to learn how to read one.

​Start with Doctor

​Connection Problems

​Authentication Problems

​Configuration Problems

​Tool Problems

​Still Stuck?

​What’s Next

Start with Doctor

Connection Problems

Authentication Problems

Configuration Problems

Tool Problems

Still Stuck?

What’s Next