Using Earnie Through MCP

Earnie’s MCP server offers a set of 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 the agent chooses the tool, fills in the arguments, and reports the answer to you. The examples on this page are requests you can give your agent. The argument names are there so you can recognise them in the agent’s output, or ask for one by name.

​

Before You Ask

​

Which Tools the Agent Can See

The agent sees only the tools your API key’s permissions allow. If the key lacks a tool’s permission, the tool doesn’t appear at all. If the agent tries to call it anyway, Earnie refuses with a message that names the missing permission. See 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.
3. The key’s project, if the key is restricted to exactly one.

If none of these applies, the tool asks for a project and lists up to 20 of the projects the key can reach. Earnie refuses a project the key can’t reach with the same message as a project that doesn’t exist, so the agent can’t use it to discover other projects. Two tools work differently: earnie_project_posture and earnie_search_findings. A project is optional for them. With no project argument and no default project header, they cover every active project the key can read, so the agent can answer questions about the whole organisation. If your client sets a default project, they cover only that project unless the agent names another.

​

Long Lists

Three tools return lists: earnie_list_projects, earnie_project_posture, and earnie_search_findings. earnie_project_posture returns a list only when it covers several projects. They return 50 rows by default. The agent can ask for between 1 and 200 with limit, and fetch the next page with the next_cursor value from the previous answer.

​

The Tools

​

platform_health_ping

Checks the connection. It works with any valid key, and returns a status of ok, the server’s current time, and the server’s name and version.

Ping Earnie to check the connection is working.

​

earnie_list_projects

Lists the active projects your key can reach, with each one’s name, slug, ID, and Dashboard link. The agent calls this first when it doesn’t know which project you mean, or when Earnie rejected a project it named. The list ignores a default project, so it always shows everything the key can reach. Archived projects aren’t listed. To ask about one, name it.

Which Earnie projects can you see?

​

earnie_project_posture

Reports a project’s governance posture, the same state its Dashboard shows. This is the project’s standing state. A pull request’s Earnie check is judged separately, on the findings that change introduces. See Merge gate. The answer covers:

• The gate: block, require, warn, pass, or none. require means findings are held until a Policy Approval is granted, so treat the project as not mergeable. none means no policy has been evaluated, which is not a pass.
• What needs attention: conditions such as a blocked gate, an approval that’s needed, a project that’s never been scanned or has a stale scan, or a missing SBOM or notice file. An empty list isn’t an all-clear. A warning gate, open CVEs, and weak cryptography don’t appear there, so read the gate and the counts as well.
• Counts: open high and critical CVEs, weak cryptography, licences Earnie couldn’t classify, weak-copyleft licences, and open AI provenance findings.
• The cryptography funnel, for a single project: the distinct assets, how many your code reaches from an entry point, how many of those are weak or quantum-vulnerable, and how many a policy blocks. It’s the same funnel as the project’s Cryptography page. When no call path was traced, the funnel says reachability wasn’t analysed instead of reporting zeros.
• The scan the figures come from, for a single project: its coverage, when it finished, and whether it ran the cryptography and AI provenance scanners.
• Enforcement over the last four weeks (activity): pull request and CI checks by gate, agent self-checks by gate, and code-review calls by outcome (ok, rejected, failed), summed over the projects the answer covers. ok means the review answered, not that it passed. activity is null when Earnie couldn’t read it, never zeros.

With no project named and no default project set, the answer covers every active project the key can read, worst gate first, with a count of projects at each gate. To ask about an archived project, name it. A null count means Earnie never measured it, for example because that scanner has never run. It never means zero. A project that was scanned and is clean shows 0. The weak-cryptography count (weak_crypto) is stored rather than computed on each call. weak_crypto_as_of says when it was last calculated. While it’s being recalculated, weak_crypto_updating is true and the figure is the previous count, which may change.

Is the payments-service project currently blocked?

Which of our projects have a blocking gate 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. It doesn’t see code that hasn’t been scanned, so to check code the agent has just written, it uses earnie_review_code instead. The agent can narrow the search with these arguments: Each row includes the finding’s ID, which earnie_get_finding and earnie_triage_finding use, a summary of its evidence, and a link to it.

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

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

​

earnie_get_finding

Reads one finding in full. The agent usually calls it after a search, when it’s about to explain or fix one finding. Reading a finding never changes it. The answer includes:

• the finding’s stored evidence
• for a component, its licence, known vulnerabilities, and, where Earnie has assessed it, what to do about the component
• for a cryptographic finding, its export-control purpose and signals
• the policy verdicts that judge it, and whether it currently counts towards the gate, taking any Policy Approval into account
• a link to it in the Review Workspace

By default the answer is concise, and leaves out cryptographic call chains. With response_format: detailed, it returns the full stored evidence, up to 256 KiB. If the evidence is larger, the answer stays concise and says so with evidence_truncated: true.

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, for the agent to follow. The agent should call it once at the start of a session, or when the project changes. It describes what’s forbidden. It doesn’t check code: earnie_review_code does that.

• 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. If the policies don’t all fit, truncated is true, and the block holds fewer rules than are in force.
• format: json returns one entry for each policy.
• domain narrows the rules to oss, crypto, or ai. The default, all, covers every domain.

A policy that nobody has written a plain sentence for appears as its rule expression, starting “Enforced by this CEL rule:”. The answer also lists those policies under needs_rule, and policies whose rule may be out of date under stale. Pass both lists to whoever owns your policies.

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

​

earnie_try_policy

Runs a draft rule on a project’s findings without saving anything, and says what it would do, for example “would block 12 of 340 findings in billing-service”. Pass the project and the draft: domain (oss, crypto or ai), action (block, warn or require), expression, parameter_spec, values and an optional name. The answer lists up to ten of the findings the rule would flag, each with the conditions that matched it. If the rule reads data the project’s latest scan didn’t collect, the answer names that data and counts nothing. A draft Earnie can’t accept returns an error that says why, the same way saving it would.

Before you propose this rule, try it on billing-service and tell me what it would block.

​

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, uses cryptography, or calls an AI SDK, model, or agent framework. The agent sends either the changed files or a unified diff, not both. Every file needs a path, even an invented one such as snippet.go, because policies depend on file extensions and manifest names. Earnie reviews only what it’s sent, never a whole repository. It doesn’t review AI model files: those are identified when the repository is scanned. Each call creates a Self-check. A Self-check creates no findings and doesn’t change the project’s posture. The answer gives:

• A gate: pass, warn, block, require, error, or none. error means a policy that applies is missing the evidence it needs. none means no policy applied, which is not a pass.
• Each violation, worst first, with a suggested fix.
• Which scanners ran. A policy whose scanner didn’t run is listed as not evaluated, never as passed.
• Files Scan Configuration excluded, if any. The gate doesn’t cover them.

The coverage is always partial, because Earnie judged only what the agent sent. So a pass means nothing it sent broke a policy, not that the change is clear. The pull request check still decides what merges. If the review takes longer than your organisation’s wait budget, the tool returns status: "running" with a selfcheck_id. That isn’t a verdict yet. The agent calls the tool again with only the selfcheck_id to read it.

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

​

earnie_export_bom

Returns a project’s CycloneDX 1.7 bill of materials from an SBOM snapshot that already exists. The tool never creates a snapshot.

• include chooses which snapshot to export, by the sections it was generated with: ["oss"] for an SBOM of open-source components, ["crypto"] for a CBOM, ["ai"] for an AIBOM of identified AI models, or several for a combined document. Earnie returns the newest snapshot generated with exactly those sections.
• Without include, it returns the newest snapshot, whatever sections it holds.
• scan limits it to the snapshots of one scan.

A document up to 64 KiB comes back in full. For a larger one, the answer has a document_url, which the agent fetches with the same API key. The answer also says whether the snapshot is stale: true means review decisions have changed since it was made. It’s still a valid record of that moment, but not the current inventory. If no matching snapshot exists, the tool says so. Generate one from the project’s Reports page in Earnie, or ask the agent to make one with earnie_export.

Export the atlas project’s CBOM.

​

earnie_list_exports

Lists the exports that exist, newest first, with each one’s kind (sbom, cbom, aibom, notice, export-control, report, or package), its sections, who made it and when, and a link to each file. The agent calls it when you ask what exports exist, or for a project’s latest SBOM, notice, or report, and before it makes one.

• project names one project. Without it, the answer covers every project the key can read.
• kind and package narrow the list. latest keeps each project’s newest export among those that match.
• limit and cursor page through it, as in other lists.

The answer links to files, which the agent fetches with the same API key. It never returns a file’s contents.

Which exports does the atlas project have?

​

earnie_export

Makes an export of a scan and returns links to its files. It’s the agent’s form of the New export sheet.

• scan is the scan to export, and is required. The agent gets it from earnie_project_posture.
• preset chooses the kind: sbom (the default), cbom, aibom, notice, export-control, or report.
• formats chooses the files: cyclonedx or spdx, notice, export-control, or report-html, report-csv, report-xlsx, and report-pdf. Without it, the preset’s default file.
• include chooses the sections of an SBOM, CBOM, or AIBOM, as in earnie_export_bom.
• report sets a report’s template (compliance, executive, or operator) and sections. Without it, the agent gets the default report.
• package makes a compliance package and takes no other option, because the package decides its own files and sections.

Each call makes a new snapshot, so the agent should check earnie_list_exports first when the export may already exist. A report section the key can’t see, a package it can’t make, or a cryptography export from a scan with no cryptography results is refused with the reason, never left out silently. The answer links to each file and to all of them together as one ZIP with a README. The files are evidence for what they describe, not a claim that you comply with a regulation. The export appears on the project’s Reports page, attributed to the key.

Make the executive report for the atlas project’s latest scan, with the vulnerabilities and licence sections, as a PDF.

​

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. Every action also needs a reason, up to 2,000 bytes. The decision for resolve must fit the kind of finding, the same choices as in the Review Workspace: replace_component also needs a replacement_purl: the package URL, with a version, of the component that really matched, for example pkg:npm/lodash@4.17.21. Earnie refuses a decision that doesn’t fit the finding, and lists the ones that do.

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

Before you ask for a decision, know that:

• not_a_match and mark_original mean different things. not_a_match says the reported lines don’t correspond to the component; mark_original says the code is yours. Both take the finding out of the gate.
• mark_original covers only this finding. It doesn’t save a correction to Scan Configuration, the rule that keeps matching findings closed after later scans. A person can do that from the Review Workspace.
• A finding that exists only in a pull request can only be resolved or reopened. The decision applies when the code reaches the default branch.
• Repeating a decision that already stands changes nothing, and isn’t an error.

​

earnie_list_vulnerabilities

Lists the vulnerabilities (CVEs) found in one project’s components, one row per component version and CVE. Each row has the CVE and its aliases, the severity, the EPSS score, the versions that fix it, whether it’s on the CISA Known Exploited list, where the component came from, and the statement status (undecided when no one has stated anything). The answer also counts the rows in each status. The agent can filter by status, severity, kev, purl, cve, and a free-text q, and page with limit and the next_cursor value.

Which known exploited vulnerabilities in atlas have no statement yet?

​

earnie_decide_vulnerability

Records or withdraws a vulnerability statement on one or more rows from earnie_list_vulnerabilities, all or none. It needs the vulnerabilities:decide permission, which Admins and Operators hold, so it appears only for a key that has it. The agent should call it only when you’ve told it what to state. A statement is published as VEX, so it should state only what you have established. Earnie records the statement as made by an agent, and keeps every revision in the row’s history.

In atlas, state that CVE-2021-44228 in log4j-core 2.14.1 is not affected, because the vulnerable code is never run.

​

What earnie_list_exposures shows

Where CRA reporting is switched on, an agent that lists the exposures also sees each one’s vulnerability statement. When an exposure nobody has decided about has a Not affected statement, the list suggests the matching dismiss reason, taken from the statement’s justification. It’s only a suggestion: Earnie never dismisses on a statement, and a case that’s already open is closed, not dismissed.

​

earnie_attach_policy and earnie_detach_policy

Attach puts an existing organisation policy in force on one project, so its rule gates that project’s findings from then on. Detach takes it out of force on that project only. The policy and its other attachments stay. Neither tool creates or edits a policy. These tools need a key with policies:write. The Coding agent (MCP) preset doesn’t include it, so create a key and add the permission under Adjust exact permissions. See API keys. Both tools act on one project, chosen as described above. The result says what happened: Both tools are safe to repeat. A policy that doesn’t exist, and one the key can’t see, get the same answer.

Attach the “Warn on weak copyleft” policy to payments-api.

​

What’s Next

If a tool doesn’t behave as expected, see Troubleshooting.