Skip to content
Bugb Docs

Use bugb from an agent

bugb mcp serves eleven tools over stdio: the threat model, the findings ledger, the advisories and the run history of every repository scanned on this machine. Ten of them are read-only, and none of them sends traffic at a target.

Register it when an agent working in your codebase should know which threats are already proven, which were ruled out, and which were never tested — none of which is derivable from the source.

Before you start

Section titled “Before you start”
  • bugb on your PATH, and at least one run on this machine to read.
  • An MCP client. The example below is Claude Code.

Register it

Section titled “Register it”
.mcp.json
{
  "mcpServers": {
    "bugb": {
      "command": "bugb",
      "args": ["mcp"]
    }
  }
}

Claude Code picks that up from the project root and asks before using it:

Terminal window
claude mcp list
bugb: bugb mcp - ⏸ Pending approval (run `claude` to approve)

Truncated to the bugb line — the command lists every server the client knows.

What it serves

Section titled “What it serves”

Interrogated over the protocol, the server registers eleven tools:

Tool Arguments Returns
list_repositories — every repository bugb has scanned, newest first, with exposure, probed and confirmed counts
get_repository key one repository’s latest scan: the full guardlink table plus its advisories
get_advisory run_id, key one finding’s write-up, its probe template, and the evidence
list_runs — runs that can still be resumed
get_run run_id one run’s manifest, ledger stats, confirmed and outstanding findings
get_events run_id, since, limit progress events after a cursor
get_report run_id, name one of a run’s markdown reports
get_artifact run_id, kind a model-tier artifact: threat-model report, dashboard, or SARIF
generate_model repo runs something: builds the threat model and dashboard. No traffic
request_verification run_id, key the commands to get findings verified. Starts nothing
list_environments — known environments, and whether their sessions are live

Every tool but generate_model declares readOnlyHint: true, and every tool declares openWorldHint: false — the server reads this machine’s own run directory and reaches nothing else.

It cannot start a scan, on purpose

Section titled “It cannot start a scan, on purpose”

request_verification is the tool an agent reaches for when it wants a finding proven, and it deliberately does not run anything. It returns the flow, filled in for that run: the exposures in scope and the exact commands.

That flow is three steps, and the middle one is a person:

  1. bugb intake "<brief>" — the agent can compose the brief and print the plan id.
  2. bugb intake --approve <PLAN_ID> — the operator approves. Approving is the authorization, and it is not a decision an agent may make on someone’s behalf.
  3. bugb auto --plan <PLAN_ID> — the loop runs.

The server’s own instructions say so to the agent that connects: the test loop runs from the CLI, through a plan the operator approves, and an agent must not assemble its own scan out of guardlink and cxg instead.

Section titled “Related”