Skip to main content
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 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 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

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

​
earnie_get_finding

Reads one finding in full: its stored evidence, the policy verdicts that judge it, whether a Policy Approval currently lets it through, and a link to it in the Review Workspace. 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: 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.
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. By default, a key can start 30 reviews a minute. Checking on a running review doesn’t count towards that.

​
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, 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. The decision for resolve matches the decisions in the Review Workspace: 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”.
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.

​
What’s Next

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