MCP server

Bomly can run as a local Model Context Protocol (MCP) server. This lets an MCP-aware agent call Bomly's dependency graph tools directly instead of asking you to paste scan output into chat.

The server is local and stdio-based:

• the MCP client starts bomly mcp serve as a child process
• Bomly reads the same project files the CLI can read
• tool results are returned as structured JSON
• Bomly does not host a remote MCP endpoint

Prerequisites

Install Bomly first and make sure the bomly executable is on PATH:

bomly version

If that command fails, install Bomly from Installation or use the absolute path to the binary in your MCP client config.

Start the server by hand when you want to check that the command works:

bomly mcp serve

The command writes its startup banner to stderr and then waits for an MCP client on stdio. It is not meant to be used as an interactive shell command after startup.

Without Installing The CLI First

If you would rather not install Bomly separately, the bomly-mcp npm package starts the same server:

npx -y bomly-mcp

Its install step downloads the release archive for your platform from GitHub Releases and checks it against SHA256SUMS, the file published with each release that lists the SHA-256 checksum of every archive in it. If the archive's checksum does not match the one listed there, the install fails and nothing is unpacked. Otherwise the binary is unpacked inside the package, together with the LICENSE, NOTICE, and licenses/ files the archive carries. Set BOMLY_MCP_VERSION to pin a different CLI version.

Anywhere below that a config uses "command": "bomly" with "args": ["mcp", "serve"], you can use "command": "npx" with "args": ["-y", "bomly-mcp"] instead. If bomly is already on PATH, prefer it: the server starts faster and you update it with your package manager.

Claude Code

Add Bomly as a local stdio server:

claude mcp add --transport stdio bomly -- bomly mcp serve

Or, without a separate CLI install:

claude mcp add --transport stdio bomly -- npx -y bomly-mcp

For a project-scoped config you can also commit a .mcp.json file:

{
  "mcpServers": {
    "bomly": {
      "type": "stdio",
      "command": "bomly",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Claude Code prompts before using project-scoped servers from .mcp.json. Use /mcp inside Claude Code to inspect the connection and available tools.

Cursor

Create or update .cursor/mcp.json in a project, or ~/.cursor/mcp.json for your user:

{
  "mcpServers": {
    "bomly": {
      "type": "stdio",
      "command": "bomly",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Then open Cursor's MCP settings and confirm that the Bomly server is enabled. If Cursor cannot start the server, run bomly mcp serve in a terminal from the same environment Cursor uses.

VS Code

Create or update .vscode/mcp.json in a workspace, or your user MCP config:

{
  "servers": {
    "bomly": {
      "type": "stdio",
      "command": "bomly",
      "args": ["mcp", "serve"]
    }
  }
}

Use the command palette action MCP: List Servers or MCP: Open Workspace Folder MCP Configuration to inspect the server. VS Code also supports sandbox settings for local stdio servers if you want to restrict filesystem or network access.

Tools

Bomly registers four MCP tools.

MCP coverage matches Bomly CLI coverage: bomly_scan, bomly_explain, and bomly_diff use the same detector, matcher, auditor, and analyzer registry as the CLI. See Support Matrix for the current ecosystem and package-manager list.

The policy arguments shared by scan, explain, and diff are fail_on, allow_vulnerability_ids, allow_licenses, deny_licenses, license_exempt_packages, deny_packages, deny_groups, protected_packages, typosquat_threshold, typosquat_mode, warn_only, and baseline. Per-call values layer over the server's resolved configuration and are validated with the same rules as CLI flags.

Compact Responses And Drill-Down

MCP tool results land in an agent's context window, so they use a compact response shape (schema_version: "mcp/1"), sized for tool-result limits and versioned independently of the CLI JSON documents in JSON Schemas. A realistic enriched scan that serializes to megabytes as a full document comes back as a few KB of actionable data.

bomly_scan returns:

• summary — manifest/package counts, subprojects and modules counts for scans that span nested projects or workspace/reactor members (omitted for flat scans), vulnerable vs clean packages, findings by severity, and whether enrich/audit ran. A clean non-audited scan also returns a capped package inventory. The full hierarchy is derived from manifests[].subproject + path in the complete CLI JSON document.
• remediations — possible changes for vulnerable packages. Each group names the package and, when known, the manifest to update. Bomly sorts the most urgent groups first. recommended_version appears only when the available data supports one complete recommendation.
  • direct-bump means updating a package declared directly in the project.
  • transitive-override means pinning an indirect package with the package manager's override feature.
  • lockfile-refresh means asking the package manager to resolve a newer indirect package version.
  • no-fix-upstream means the advisory source says no fixed version exists.
  • manual-review means the available data does not support a specific change.
• informational — findings that do not currently require a change. This includes warning-only findings and vulnerabilities allowed by audit policy or below the selected failure threshold.
• diagnostics — pipeline warnings (detector fallbacks, matcher failures) so partial results explain themselves, plus the CI-readiness warnings detectors record while resolving: package-manager, lockfile-format, and install-policy mismatches that fail a CI install even after the vulnerability is fixed.
• truncation — explicit counters whenever a cap cut anything; nothing is dropped silently.

Each finding carries advisory identifiers (vuln_id, aliases), severity, classification (fix_available, no_fix_upstream, wont_fix, policy_only), the shortest dependency path, and KEV/EPSS/reachability signals — but no descriptions, reference URLs, or CVSS vectors.

For the omitted detail:

• One package: call bomly_explain with enrich. Its response carries the package's full advisory records and remediation context, bounded to that package. Add audit when you also need policy results; audit requires enrich.
• The complete document: run the CLI (bomly scan --format json -o <file>). The MCP server intentionally never returns the full scan document; it does not fit tool-result limits on real projects.

With enrich, bomly_diff returns remediation groups for vulnerable packages on the head side. With audit (which requires enrich), it also returns findings bucketed into a security_delta: introduced, resolved, and persisted. By default base and head are Git refs; set image to compare two container tags or digests, or sbom: true to compare two SBOM files.

Example Prompts

After the server is connected, ask your agent for focused dependency tasks:

Use Bomly to scan this project and summarize high-severity findings.

Use Bomly to explain why lodash is present before changing package.json.

Use Bomly to diff this branch against main and tell me whether the PR introduces new vulnerable dependencies.

For repeatable team behavior, put a short instruction in your repository's agent guidance:

Before committing dependency or lockfile changes, use Bomly's MCP tools to run a dependency diff against the base branch and explain any new vulnerable package.

This is a workflow hint, not a security guarantee. Review the tool output and the proposed code changes.

Security And Network Behavior

Bomly's MCP server runs as your user on your machine. Treat it like running the Bomly CLI from the same repository:

• it can read project files that the Bomly process can access
• it can invoke package-manager tools used by detectors if those tools are on PATH
• it inherits the environment passed by your MCP client
• it does not need a Bomly account, API key, or token

Network enrichment is opt-in via enrich for bomly_scan, bomly_explain, and bomly_diff. Without enrichment, matchers do not call vulnerability, license, lifecycle, or scorecard services. Some detectors may still invoke package-manager commands, and those tools can contact package registries as part of normal dependency resolution. See Detectors for the detector-level breakdown.

Troubleshooting

A Tool Reports Only A Short Failure Category

MCP tool errors use short messages such as scan pipeline failed or diff target resolution failed. Bomly does not send raw internal errors to the MCP client because they can contain local paths, command output, URLs, or credentials.

Run the server with bomly -vv mcp serve and reproduce the request to inspect the safe stage logs emitted independently by the component that failed. The MCP error log itself records only the stable category and the Go type of the unwrapped cause, never the cause text. The MCP client must keep stdout reserved for the protocol.

Request validation uses the same short category instead of echoing the rejected value. This keeps paths, URLs, and other user input out of the protocol and logs, but it also means an agent may need to inspect the tool schema or retry with fewer options to identify an invalid combination.

spawn bomly ENOENT

Your MCP client cannot find bomly on PATH. Run:

which bomly

Then either fix the client environment or use the absolute path:

{
  "command": "/usr/local/bin/bomly",
  "args": ["mcp", "serve"]
}

The Server Starts But No Tools Appear

Check the MCP client's server status panel first. Then run:

bomly mcp serve

If the command exits immediately, fix the printed error. If you recently changed the config, restart the MCP server or reset the client's cached tool list.

A Scan Takes A Long Time

The MCP tools run the real Bomly pipeline. Large repositories, container images, Git clones, enrichment, and build-tool-backed detectors can take longer than small lockfile-only scans.

Use narrower arguments when possible:

{
  "path": "./services/api",
  "scope": "runtime"
}

For clients with per-tool timeouts, increase the timeout for the Bomly server rather than retrying the same scan in a loop.

A Detector Says A Package Manager Is Missing

Bomly does not install package managers for you. Install the package manager the project uses, or scan from an environment where that tool is already available. Lockfile-parser detectors and SBOM ingest do not need package-manager binaries.

I Need The Full Scan Document

MCP responses are intentionally compact. When an agent (or you) needs the complete three-collection JSON document, run the CLI instead: bomly scan --format json -o scan.json. For advisory detail on a single package, bomly_explain returns it without the size cost.

A Scan Says "No Subprojects Discovered"

The error is a short report: the target and search scope, any active filters, and every manifest candidate that exists under the target with the reason discovery skipped it (- web/package.json (npm) — skipped: not scanned without --recursive, or — skipped: excluded by --ecosystems go; a reason shared by every candidate is stated once in the section header). Check that the path argument points at the project root and that no ecosystems filter excludes what is actually there. When the probe reports manifests in subdirectories only (a monorepo of independent projects), pass recursive: true — discovery inspects only the target root by default. max_depth and exclude bound the recursive walk; see Scan targets.