Skip to main content
Connecting a client takes three steps: create an API key for the agent, add Earnie’s MCP server to the client, and check the connection. This page covers each one. 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.
  1. In Earnie, go to Settings → API keys and select Generate key.
  2. Name the key after the agent 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. Choose the projects the key can reach, and its expiry.
  6. Generate the key, and copy it straight away. It’s shown only once.
The Coding agent (MCP) preset grants these permissions. Each one makes certain tools visible to the agent: A tool whose permission the key lacks is hidden from the agent entirely. Using Earnie Through MCP describes each tool.

​
Step 2: Find Your MCP Address

Earnie’s MCP server is part of your Earnie deployment, at your Earnie address followed by /mcp/v1. For example, if you open Earnie at https://acme.earnie.example, the MCP address is:
Each deployment has its own address. The panel that shows your new key also shows this address, and builds its install snippets with it.

​
Step 3: Add Earnie to Your Client

There are two ways to connect. Choose one:

​
Option A: Set Up with the Earnie CLI

This is the recommended route for a repository, because it also writes your project’s policies into the agent’s instructions file and installs review hooks.
  1. Install the Earnie CLI.
  2. Sign in with the key you created:
  3. From inside your repository, run setup:
Setup detects the clients installed on your machine and preselects them. It works out the project from --project, EARNIE_PROJECT, or the repository’s Git remote, and asks you to pick one if none of those identifies it. It then writes:
  • The connection — the MCP address and your key, in each client’s user-level configuration, under a server named earnie.
  • The managed policy block — your project’s policies as plain rules, in CLAUDE.md, .cursor/rules/earnie.mdc, .github/copilot-instructions.md, or AGENTS.md.
  • Review hooks — for Claude Code, Cursor, and Codex.
Restart your client after setup so it picks up the new configuration. For the full list of flags, the exact file each client uses, and how to remove the setup again, see Connecting a Coding Agent in the CLI reference.
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.

​
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 an install snippet for each client. The snippets are built with your own MCP address, and they’re shown only once, with the key. Some snippets carry the key itself. Others leave it out, so the key doesn’t end up in your browser history. Follow the instructions for your client:

​
Claude Code

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

​
Cursor

Open the link from the panel. Cursor offers to install the server, already configured. The link doesn’t contain your key, so set it as an environment variable named EARNIE_API_KEY before you start Cursor. The installed configuration reads it as Bearer ${env:EARNIE_API_KEY}.

​
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. The link itself doesn’t contain the key.

​
Codex

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

​
Setting a Default Project

If the key can reach more than one project, the panel offers Default project for this client. Choosing one adds an X-Earnie-Project header to the snippet, set to that project’s ID:
The agent then uses that project whenever it doesn’t name one. The header never widens what the key can reach. Without a default, the agent has to name a project in every question, unless the key can reach only one project. See How the Agent Chooses a Project.

​
Claude.ai and ChatGPT

Claude.ai and ChatGPT connect from the vendor’s own cloud rather than your machine. That means:
  • they need an Earnie deployment that’s reachable from the public internet, so an on-premise Earnie can’t be used with them
  • they expect 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. It can add a custom connector with a fixed header: enter the name Authorization and the value Bearer <key>, including the space after Bearer. A Claude connector’s authentication can’t be edited afterwards, so rotating the key means removing the connector and adding it again. For a developer working in a repository, the four clients above are the supported route.

​
Step 4: Check the Connection

  1. Restart your client, 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 the server’s status, the current timestamp, 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 you set up with the Earnie CLI, you can also check the installation from the command line, without changing anything:
Doctor reports whether your key is valid, which project it would use, and each Earnie tool’s visibility, including why a tool is missing if it is. If either check fails, see Troubleshooting.

​
For Administrators: Deployment Settings

The MCP server is always available on every Earnie deployment. There’s no setting to turn it on. These environment variables, set on the Earnie deployment, change how it behaves: Without EARNIE_MCP_REVIEW_BUDGET_SECONDS, the wait comes from Settings → Scan Configuration, on the Self-check tab, under Self-check wait budget. Its default is 45 seconds.

​
What’s Next

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