> ## 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. # Connecting an AI Client > How to create an API key for a coding agent, connect Claude Code, Cursor, VS Code, or Codex to Earnie's MCP server, and check that the connection works. 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](/en/latest/earnie/mcp/overview) 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 ` 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](/en/latest/earnie/administration/api-keys#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: | Permission | Tools It Unlocks | | ---------------- | ----------------------------------------------------------------------- | | (any valid key) | `platform_health_ping` | | `projects:read` | `earnie_list_projects` | | `findings:read` | `earnie_search_findings`, `earnie_get_finding` | | `scans:read` | `earnie_project_posture`, `earnie_export_cbom` | | `policies:read` | `earnie_policy_context` | | `scans:write` | `earnie_review_code` | | `findings:write` | `earnie_triage_finding` (only with **Allow agents to triage findings**) | A tool whose permission the key lacks is hidden from the agent entirely. [Using Earnie Through MCP](/en/latest/earnie/mcp/tools) 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: ```text theme={null} https://acme.earnie.example/mcp/v1 ``` 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: | Route | Best For | What You Get | | ----------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ | | **Earnie CLI (`earnie mcp setup`)** | Working in a repository | The MCP connection, a managed policy block, and review hooks, set up in one command. | | **Install snippet from Earnie** | Connecting a client quickly, or without the CLI | The MCP connection only. | ### 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](/en/latest/earnie/using-earnie/earnie-cli#installing). 2. Sign in with the key you created: ```bash theme={null} earnie auth login --api-url https://acme.earnie.example ``` 3. From inside your repository, run setup: ```bash theme={null} earnie mcp 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](/en/latest/earnie/using-earnie/earnie-cli#connecting-a-coding-agent-mcp) 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: ```bash theme={null} claude mcp add --transport http earnie https://acme.earnie.example/mcp/v1 --header "Authorization: Bearer " ``` #### 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: ```toml theme={null} [mcp_servers.earnie] url = "https://acme.earnie.example/mcp/v1" [mcp_servers.earnie.http_headers] Authorization = "Bearer " ``` #### 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: ```text theme={null} X-Earnie-Project: ``` 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](/en/latest/earnie/mcp/tools#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 `, 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: ```bash theme={null} earnie mcp doctor ``` 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](/en/latest/earnie/mcp/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: | Variable | What It Controls | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `EARNIE_MCP_ALLOWED_ORIGINS` | Browser origins allowed to call the MCP server, separated by commas. Empty means same host only. Requests with no `Origin` header, which is how MCP clients connect, are always allowed. | | `EARNIE_MCP_REVIEW_RATE_PER_MIN` | How many code reviews one API key can start per minute. The default is 30. A negative value removes the limit. | | `EARNIE_MCP_REVIEW_BUDGET_SECONDS` | How long `earnie_review_code` waits for a result before returning. It overrides the organisation's **Self-check wait budget**. The wait is always capped at 120 seconds. | 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](/en/latest/earnie/mcp/tools) for what each tool does and how to ask for it.