Skip to main content
Connecting a client takes four steps:
  1. Create an API key for the agent.
  2. Find your MCP address.
  3. Add Earnie to your client, with the Earnie CLI or with an install snippet.
  4. Check the connection.
If you haven’t read it yet, Earnie MCP explains what the connection gives you and what you need first.

​
Step 1: Create an API Key

The client authenticates to Earnie with an API key, sent with every request as an Authorization: Bearer <key> header. Creating a key needs the Admin or Operator role. If you have neither, ask someone who does to create the key and pass it to you securely. Only the person who creates the key sees the install snippets in Option B, so ask them for the snippet for your client too, or use the Earnie CLI in Option A.
  1. In Earnie, go to Settings → API Keys and select Generate key.
  2. Under Key name, name the key after the agent and person that will use it, for example claude-code-alex.
  3. Under What this key will hold, choose the Coding agent (MCP) preset.
  4. Leave Allow agents to triage findings off unless you want the agent to record triage decisions. See Letting an agent triage.
  5. Under Projects, tick each project the agent should reach. The preset switches Projects to Specific, so you must tick at least one. To include every project, even ones created later, choose All projects instead.
  6. Under Expires in, choose 30 days, 90 days (the default), 365 days, or Custom for a date up to a year away.
  7. Select Generate, and copy the key straight away. Earnie shows it only once.
The Coding agent (MCP) preset grants these permissions. Each one makes certain tools visible to the agent: If the key lacks a tool’s permission, the agent doesn’t see that tool at all. The agent also sees only the projects the key can reach. Using Earnie through MCP describes each tool.

​
Step 2: Find Your MCP Address

Earnie’s MCP server is part of your Earnie, at your Earnie address followed by /mcp/v1. For example, if you open Earnie at https://your-company.earnie.dev, the MCP address is:
Each Earnie has its own address. The panel that shows your new key also shows this address and uses it in its install snippets. The Earnie CLI needs only your Earnie address, without /mcp/v1. It adds the path itself when it sets up a client.

​
Step 3: Add Earnie to Your Client

You can connect in one of two ways:

​
Option A: Set Up with the Earnie CLI

We recommend this route for a repository, because the agent gets your project’s policies in its instructions file, and its changes are checked at the end of each turn.
  1. Install the Earnie CLI.
  2. Sign in with the key you created. The CLI asks for the key:
  3. From inside your repository, run setup:
  4. Restart your client, so it loads the new configuration.
Setup detects Claude Code, Cursor, VS Code, and Codex on your machine and preselects the ones it finds. It takes the project from --project, the EARNIE_PROJECT environment variable, or the repository’s Git remote. If none of those identifies the project, setup asks you to pick one from the projects your key can reach. In a script, there’s no one to answer, so pass --client detected or a list such as --client claude,codex, and name the project with --project or EARNIE_PROJECT. To see every change before setup writes anything, add --dry-run. Setup then writes:
  • The connection. The MCP address and your key go in each client’s user-level configuration, under a server named earnie.
  • The managed policy block. Your project’s policies, as plain rules, go in the client’s instructions file in the repository: CLAUDE.md, .cursor/rules/earnie.mdc, .github/copilot-instructions.md, or AGENTS.md.
  • Review hooks, for Claude Code, Cursor, and Codex. At the end of each turn, a hook sends the agent’s changed files for a Self-check. Pass --no-hooks to leave them out.
  • A session-start hook, for the same three clients. It refreshes the managed policy block when the project’s policies change. See Keeping the policy block current.
VS Code gets the connection and the policy block, but no hooks, because VS Code’s hook support is still in preview.
Codex needs one more step. Codex doesn’t run project hooks until you approve them. Inside Codex, run /hooks and trust Earnie’s hook definitions.
For every flag, the exact file each client uses, and how to remove the setup again, see Connecting a coding agent in the CLI reference.

​
Option B: Use an Install Snippet from Earnie

When you generate a key with the Coding agent (MCP) preset, the panel that shows the key also shows Connect your coding agent, with a tab for each client. Each snippet already contains your MCP address. The panel appears only once, with the key. If you close it before you copy a snippet, generate a new key. Some snippets include the key. The Cursor and VS Code snippets are links you open, so they leave the key out, and it doesn’t end up in your browser history. Follow the steps for your client, then restart it. The examples below show only the Authorization header. If the panel sets a default project, your snippet also has an X-Earnie-Project header. See Setting a Default Project.

​
Claude Code

Run the command in the repository you want the agent to work in. It includes your key:

​
Cursor

  1. Set your key as an environment variable named EARNIE_API_KEY, where Cursor will see it, before you start Cursor.
  2. Open the link from the panel. Cursor offers to install the server, already configured.
The installed configuration sends the key as Bearer ${env:EARNIE_API_KEY}, so Cursor reads it from that variable.

​
VS Code

Open the link from the panel. VS Code offers to install the server in your user profile, and asks for your key as a password when you install it.

​
Codex

Add this block to ~/.codex/config.toml. It includes your key:

​
Setting a Default Project

This applies to the install snippets. A default project saves the agent from naming a project in every question. The panel sets it with an X-Earnie-Project header, set to the project’s ID:
  • If the key reaches one project, every snippet already includes the header for that project.
  • If the key reaches several projects, the panel shows Default project for this client. Pick a project, and the snippets include the header. Leave it on No default, and the agent has to name a project in every question.
The agent uses the default only when it doesn’t name a project itself. The header never widens what the key can reach. See How the agent chooses a project.

​
Step 4: Check the Connection

  1. Restart your client, if you haven’t already, so it loads the new configuration.
  2. Ask the agent to ping Earnie, for example:
    Use the Earnie health ping tool to check the connection.
    The agent calls platform_health_ping, which works with any valid key. A working connection returns a status of ok, the server’s current time, and the server’s name and version.
  3. Ask a real question, for example:
    Which Earnie projects can you see?
    The agent calls earnie_list_projects and lists the projects your key can reach, with a link to each project’s Dashboard. If a project you expected is missing, the key doesn’t include it.
If you set up with the Earnie CLI, you can also check the setup from the command line. Doctor reads your configuration and never changes it:
Doctor reports whether your key is valid, which project it would use, the state of each client’s configuration, policy block, and hooks, and whether the agent can see each Earnie tool. For a tool the agent can’t see, it gives the reason. It exits with 0 when everything is healthy, and 9 when it finds a problem. If the ping or doctor fails, see Troubleshooting.

​
When Your Key Changes

Every key expires, and a key can also be revoked. Either way, generate a new key with the Coding agent (MCP) preset, then give it to the client:
  • If you set up with the Earnie CLI, run earnie auth login again with the new key. It also updates the key in the client configurations that setup wrote.
  • If you used an install snippet, add the client again with the snippet shown with the new key, replacing the old earnie server.

​
Claude.ai and ChatGPT

Claude.ai and ChatGPT connect from the vendor’s own cloud rather than your machine. This has two consequences:
  • They can only reach an Earnie that the public internet can reach. An Earnie on your own network can’t be used with them. See Deployment and data flow.
  • They expect to sign in with OAuth, which Earnie doesn’t offer yet, so an API key alone isn’t enough.
The one exception is a Claude.ai organisation in Anthropic’s Request headers beta. Such an organisation can add a custom connector with a fixed header:
  • Name: Authorization
  • Value: Bearer <key>, including the space after Bearer
You can’t edit a Claude connector’s authentication afterwards. To replace the key, remove the connector and add it again. For a developer working in a repository, the four clients on this page are the supported route.

​
For Administrators: MCP Behaviour

Every Earnie runs the MCP server, and there’s no setting to turn it on. These limits apply to every client:
  • Review rate. One API key can start up to 30 code reviews a minute. Checking back on a review that’s still running doesn’t count. Past the limit, the agent is told how long to wait before trying again.
  • Review wait. earnie_review_code waits for a result for as long as the organisation’s Self-check wait budget allows. If the review isn’t finished by then, the agent gets a handle to check back with. You set the budget in Settings → Scan defaults, on the Self-check tab. Its default is 45 seconds, it can’t exceed 120 seconds, and an agent can’t change it.
  • Browser access. Earnie always accepts requests from MCP clients such as the four on this page. It refuses a call from a web page on another site unless that site has been allowed for your Earnie.
The review rate and the allowed browser origins aren’t in the web app. If SCANOSS hosts your Earnie, contact SCANOSS support to change them. If you host it yourself, they’re part of your deployment’s configuration.

​
What’s Next

With the client connected, see Using Earnie through MCP for what each tool does and how to ask for it.