> ## 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.

# Using Earnie Through MCP

> The Earnie MCP tools a coding agent can call, what each one does, the permission it needs, and example requests you can give your agent.

Earnie's MCP server offers nine **tools**. Each tool is one specific question or action, such as "search this project's findings" or "review this code against policy".

You don't call tools directly. You ask your agent in plain language, and it chooses the tool, fills in the arguments, and reads the answer back to you. The examples on this page are requests you can give your agent.

## Before You Ask

### Which Tools the Agent Can See

The agent sees only the tools your API key's permissions allow. A tool whose permission the key lacks doesn't appear at all. If the agent tries to call one anyway, Earnie refuses with a message naming the missing permission. See [Step 1: Create an API Key](/en/latest/earnie/mcp/connecting-a-client#step-1-create-an-api-key) for which permission unlocks which tool.

### How the Agent Chooses a Project

Most tools act on one project. Earnie decides which one in this order:

1. **The `project` argument**, if the agent passes one. It can be the project's ID or its slug (the short name in its URL).
2. **The `X-Earnie-Project` header**, if your client configuration sets a [default project](/en/latest/earnie/mcp/connecting-a-client#setting-a-default-project).
3. **The key's only project**, if the key can reach exactly one.

If none of these applies, the tool asks for a project and lists up to 20 the key can reach. A project the key can't reach is refused with the same message as one that doesn't exist.

Two tools, `earnie_search_findings` and `earnie_project_posture`, also work without a project. They then cover every active project the key can read, which suits organisation-wide questions.

### Long Lists

Tools that return lists return 50 rows by default. The agent can ask for between 1 and 200, and fetch the next page with the `next_cursor` value from the previous answer.

## The Tools

| Tool                     | What It Does                                             | Permission       | Changes Anything?    |
| ------------------------ | -------------------------------------------------------- | ---------------- | -------------------- |
| `platform_health_ping`   | Checks the connection.                                   | Any valid key    | No                   |
| `earnie_list_projects`   | Lists the projects the key can reach.                    | `projects:read`  | No                   |
| `earnie_project_posture` | Reports a project's merge gate and what needs attention. | `scans:read`     | No                   |
| `earnie_search_findings` | Searches a project's findings.                           | `findings:read`  | No                   |
| `earnie_get_finding`     | Reads one finding in full.                               | `findings:read`  | No                   |
| `earnie_policy_context`  | Returns the project's policies as plain rules.           | `policies:read`  | No                   |
| `earnie_review_code`     | Reviews code against the project's policies.             | `scans:write`    | Creates a Self-check |
| `earnie_export_cbom`     | Returns the project's CycloneDX bill of materials.       | `scans:read`     | No                   |
| `earnie_triage_finding`  | Records a triage decision on a finding.                  | `findings:write` | **Yes**              |

### `platform_health_ping`

Returns the server's status, the current time, and the server's name and version. Use it to check the connection. It works with any valid key.

> Ping Earnie to check the connection is working.

### `earnie_list_projects`

Lists the projects your key can reach, with each one's slug, ID, and Dashboard link. The agent calls this first when it doesn't know which project you mean, or when a project it named was rejected.

> Which Earnie projects can you see?

### `earnie_project_posture`

Reports a project's governance posture: its merge gate, what needs attention, its open high-severity CVE and weak-cryptography counts, and the scan those figures were measured from. Without a project, it covers every project the key can read.

> Is the payments-service project currently blocked from merging?

> Which of our projects have a blocking verdict right now?

### `earnie_search_findings`

Searches findings in a project that Earnie has already scanned: open-source matches, declared dependencies, cryptographic assets, and AI provenance. The agent can narrow the search by:

* **`domain`** — `oss`, `crypto`, `ai`, or `all` (the default)
* **`family`** — a finer category within a domain, such as `deps` for declared dependencies only
* **`state`** — `open`, `assigned`, `resolved`, `superseded_by_rule`, or `reopened`
* **`purl`** — a component's package URL, with or without a version, for example `pkg:npm/lodash`
* **`path_prefix`** — a file, or a directory to search beneath
* **`scan`** — only the files one scan covered (needs `project`)

It returns each finding's ID, which `earnie_get_finding` and `earnie_triage_finding` use.

> What open cryptography findings does the atlas project have under `src/auth`?

> Show me every finding for pkg:npm/lodash in this project.

<Note>
  An `open` finding isn't necessarily outstanding. A suppressed finding stays
  `open`, so ask about the gate with `earnie_project_posture` if you want to
  know what's actually blocking.
</Note>

### `earnie_get_finding`

Reads one finding in full: its stored evidence, the policy verdicts that judge it, whether a [Policy Approval](/en/latest/earnie/using-earnie/merge-gate#route-3-request-an-approval) currently lets it through, and a link to it in the [Review Workspace](/en/latest/earnie/using-earnie/triaging-findings). The agent usually calls it after a search, when it's about to explain or fix one finding.

By default the answer is concise. With `response_format: detailed`, it includes the full stored evidence, such as cryptographic call chains, up to 256 KiB.

> Explain why that lodash finding is blocking, and what would fix it.

### `earnie_policy_context`

Returns the policies in force for a project as plain rules, one sentence each, written for the agent to follow. The agent should call it once at the start of a session, or when the project changes.

* **`format: rules`** (the default) returns the managed policy block, capped at 4 KiB. This is the same block `earnie mcp setup` writes into your repository.
* **`format: json`** returns one entry for each policy.

> Read this project's Earnie policies and follow them while you work.

### `earnie_review_code`

Checks code against the project's policies **before** the agent shows it to you. The agent should call it after it writes or edits code that adds or changes a dependency, copies code from elsewhere, or uses cryptography.

The agent sends either the changed `files` or a unified `diff`, not both. Earnie reviews only what it's sent. Each call creates a [Self-check](/en/latest/earnie/using-earnie/self-checks): it creates no findings and doesn't change the project's posture.

If the review takes longer than the deployment's wait budget, the tool returns `status: "running"` with a `selfcheck_id`. The agent calls the tool again with only that `selfcheck_id` to read the verdict.

> Review the changes you just made against Earnie's policies before you show me the code.

<Note>
  **Limits.** One review can include up to 200 files, 512 KiB per file, and
  1 MiB in total. For anything larger, use `earnie scan diff` from the [Earnie
  CLI](/en/latest/earnie/using-earnie/earnie-cli#running-a-scan). By default, a
  key can start 30 reviews a minute. Checking on a running review doesn't
  count towards that.
</Note>

### `earnie_export_cbom`

Returns a project's CycloneDX 1.7 bill of materials, covering software components, cryptographic assets, and AI provenance, from its most recent [SBOM snapshot](/en/latest/earnie/evidence/exporting-sboms), or from a named scan's snapshot.

* A document up to 64 KiB is returned in the answer. A larger one comes back as a `document_url`, which is fetched with the same API key.
* It only reads snapshots that already exist. If the project has never generated one, the tool says so rather than creating one.

> Export the atlas project's CBOM.

### `earnie_triage_finding`

Records a triage decision on one finding. It's available only if the key was created with **Allow agents to triage findings**. The agent should call it only when you've told it what to do with a specific finding, and always pass your reason.

| Action     | What It Does                                          | Also Needs                            |
| ---------- | ----------------------------------------------------- | ------------------------------------- |
| `resolve`  | Closes the finding with a decision.                   | `decision`                            |
| `suppress` | Keeps the finding open, but removes it from the gate. | —                                     |
| `reopen`   | Undoes an earlier decision.                           | —                                     |
| `assign`   | Assigns the finding to a person.                      | `assignee` (email address or user ID) |

The `decision` for `resolve` matches the [decisions in the Review Workspace](/en/latest/earnie/using-earnie/triaging-findings#making-a-decision): `confirm_match`, `mark_original`, `replace_component`, `accept_dependency`, `dismiss_dependency`, `confirm_usage`, `false_positive`, or `accepted_risk`. `replace_component` also needs a `replacement_purl`, the versioned package URL of the component that actually matched. Every action needs a `reason`, up to 2,000 bytes.

> That match in `lib/crypto.js` is our own code. Mark it original, with the reason "written in-house in 2021".

<Note>
  **An agent's decision takes effect straight away.** A resolution from an API
  key is marked as pending human review, but the finding still closes and its
  effect on the gate applies immediately. Every decision is recorded in the
  finding's audit trail and attributed to the key. See [Letting an Agent
  Triage](/en/latest/earnie/administration/api-keys#letting-an-agent-triage).
</Note>

## What's Next

If a tool doesn't behave as expected, see [Troubleshooting](/en/latest/earnie/mcp/troubleshooting).