> ## Documentation Index > Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting Earnie MCP > How to diagnose and fix common problems connecting an AI client to Earnie's MCP server: connection, authentication, configuration, and tool errors. 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: ```bash theme={null} 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](/en/latest/earnie/mcp/connecting-a-client#step-2-find-your-mcp-address). | | `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](/en/latest/earnie/mcp/connecting-a-client#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 ` 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](/en/latest/earnie/administration/api-keys#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](/en/latest/earnie/mcp/connecting-a-client#step-1-create-an-api-key). | | "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](/en/latest/earnie/mcp/connecting-a-client#setting-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](/en/latest/earnie/using-earnie/earnie-cli#running-a-scan). | | "Project … is archived, so no new check can run in it" | Restore the project first. See [Archiving, Restoring, and Resetting](/en/latest/earnie/using-earnie/all-projects#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](/en/latest/earnie/evidence/exporting-sboms#generating-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](/en/latest/earnie/administration/api-keys#managing-keys). * Check the CLI's own reference for [setup, doctor, and uninstall](/en/latest/earnie/using-earnie/earnie-cli#connecting-a-coding-agent-mcp). ## What's Next With your agent connected, every review it runs is recorded as a Self-check. See [Self-Checks](/en/latest/earnie/using-earnie/self-checks) to learn how to read one.