MCP tools

Reference

The Audito MCP server exposes thirteen tools. Every tool authenticates from the Authorization: Bearer audt_… header on the request and runs Supabase queries under your identity — RLS enforces the same per-user/per-org access the dashboard does.

Library and finding management: list_libraries, get_library, create_library, update_library, delete_library, add_dependency, update_dependency, delete_dependency, list_findings, triage_finding, suggest_actions. Pre-install guard: check_package, audit_lockfile.

list_libraries

List every library visible to the caller, with dependency and open-finding counts.

• Args: none.
• Returns: [{ id, name, last_scanned_at, deps_count, findings_count }].

get_library

Return one library with its dependencies and currently-open vulnerability findings.

• Args:
  • id (uuid, required) — library id.
• Returns: { library, dependencies, open_findings }.

create_library

Create a new manual library with an initial dependency list. Triggers a background scan immediately.

• Args:
  • name (string, required) — display name for the library.
  • dependencies (array, required, ≥1 entry) — each entry:
    • ecosystem (enum, required) — one of npm, pypi, cargo, maven, rubygems, go, composer, nuget, debian, alpine, manual, other.
    • package_name (string, required).
    • version (string, required).
• Returns: the created library row.

update_library

Rename a library or update its notes.

• Args:
  • id (uuid, required).
  • name (string, optional).
  • notes (string | null, optional).
• Returns: the updated library row.

delete_library

Permanently delete a library and its dependencies.

• Args:
  • id (uuid, required).
• Returns: { id } on success.

add_dependency

Add a single dependency to an existing library.

• Args:
  • library_id (uuid, required).
  • ecosystem (enum, required) — same set as create_library.
  • package_name (string, required).
  • version (string, required).
• Returns: the inserted dependency row.

update_dependency

Update the version of a dependency in place.

• Args:
  • id (uuid, required).
  • version (string, required).
• Returns: the updated dependency row.

delete_dependency

Remove a dependency from its library.

• Args:
  • id (uuid, required).
• Returns: { id } on success.

list_findings

List vulnerability findings across all libraries, optionally filtered by status, severity, or library.

• Args:
  • status (enum, optional) — open, accepted, dismissed, snoozed.
  • severity (enum, optional) — CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN.
  • library_id (uuid, optional).
• Returns: array of findings.

triage_finding

Mark a (dependency, OSV id) finding as accepted, dismissed, or snoozed. Upserts a single decision row keyed on (owner, dependency_id, osv_id) — there is exactly one current decision per finding.

• Args:
  • dependency_id (uuid, required).
  • osv_id (string, required).
  • status (enum, required) — accepted, dismissed, or snoozed.
  • reason (string, optional).
  • snoozed_until (ISO 8601 datetime with offset, required when status="snoozed") — must be in the future.
• Returns: the upserted decision row.

suggest_actions

Get a deterministic next-action suggestion for a library: open findings sorted by severity, available version bumps, license violations, and a one-line summary.

• Args:
  • library_id (uuid, required).
• Returns: the structured suggestion payload.

check_package

Pre-install guard for a single package. Looks up registry metadata, OSV advisories, deprecation, and a curated typosquat list, then returns a verdict before the dependency goes anywhere near disk.

• Args:
  • ecosystem (enum, required) — npm, PyPI, Cargo (crates.io), or Go (modules via proxy.golang.org).
  • package_name (string, required).
  • requested_version (string, optional) — falls back to the registry's latest if omitted.
  • library_id (uuid, optional) — when set, scopes the license-policy lookup to that library and turns on the linked-library bridge below.
• Returns: { decision, reasons, package, suggested_alternatives, human_summary, linked_library? } where decision is allow, warn, or block.

Decision precedence (highest first): OSV malware advisory (MAL-…) → block, CRITICAL CVE → block, deprecated → block, lower-severity CVE → warn, typosquat → warn, license mismatch → warn, otherwise allow. Every triggered reason appears in reasons regardless of which one drove the verdict. License is null for Go (deps.dev is not consulted).

linked_library (only when library_id is set)

When library_id is provided, the response includes a linked_library block that ties the verdict back to your workspace state:

• library_id, library_name, package_already_tracked, matching_dependency_id — always present.
• On allow when the package is not tracked in that library: suggested_action = { tool: "add_dependency", args: {…}, why: "…" } so the agent knows to call add_dependency next.
• On warn or block when the package is tracked: the matched OSV advisories are persisted into osv_vulnerabilities and package_vulnerabilities, and findings_persisted = { dependency_id, osv_ids[] } is returned. The dashboard's findings view picks them up immediately rather than waiting for the next backend sweep.

audit_lockfile

Audit a whole lockfile in one call. Reuses the same decision engine as check_package, plus a single OSV batch query up front to pre-warm the cache so a 200-package audit runs at bounded concurrency without hammering OSV.

• Args:

  • format (enum, required) — package-lock (npm v1/v2/v3 package-lock.json) or requirements-txt (PyPI). yarn.lock, pnpm-lock.yaml, Pipfile.lock, poetry.lock, Cargo.lock, and go.sum are not yet supported.
  • content (string, required) — the raw lockfile body.
  • library_id (uuid, optional) — scopes license-policy lookup, same as check_package.
  • include_dev (boolean, optional) — default false; dev-only entries are dropped unless this is set.
  • max_packages (int, optional) — cap on packages audited per call. Default 200, hard ceiling 500. Anything above the cap is reported in summary.skipped and the result is marked truncated: true.

• Returns:

  {
    "summary": {
      "total": 142,
      "blocked": 1,
      "warned": 4,
      "allowed": 137,
      "skipped": 0,
      "elapsed_ms": 3821
    },
    "packages": [
      {
        "decision": "block",
        "reasons": [{ "code": "known_cve", "osv_ids": ["GHSA-…"], "max_severity": "CRITICAL" }],
        "package": { "ecosystem": "npm", "name": "lodash", "version_checked": "4.17.20", "latest_version": "4.17.21", "license": "MIT" },
        "suggested_alternatives": [],
        "human_summary": "`lodash@4.17.20` has a known critical vulnerability (GHSA-…). Bump to 4.17.21 or later.",
        "is_dev": false
      }
    ],
    "parse_errors": [],
    "human_summary": "Audited 142 packages: 1 blocked, 4 warned, 137 allowed. Top blocker: `lodash@4.17.20` (critical CVE).",
    "truncated": false
  }

Prefer audit_lockfile over looping check_package per dependency: it costs one OSV batch query plus N small detail fetches instead of N round trips, and it emits a single lockfile.audited activity event instead of flooding the feed with one entry per package.