MCP Server Integration in OSV-Scanner: Complete Guide to LLM-Based Vulnerability Scanning

The OSV-Scanner MCP server integration exposes vulnerability scanning capabilities via the Model Context Protocol, enabling LLM-driven tools to execute dependency scans and retrieve advisory details through JSON-RPC over STDIO or SSE.

The google/osv-scanner repository includes an experimental MCP (Model Context Protocol) server that transforms the command-line scanner into an LLM-accessible service. This integration allows AI assistants and automated tools to programmatically detect vulnerabilities without wrapping the traditional CLI, supporting both local STDIO and networked SSE transport modes.

What is the MCP Server Integration?

The MCP server integration, found under cmd/osv-scanner/mcp/, implements the Model Context Protocol—a lightweight JSON-RPC specification designed for LLM tool integration. According to the source code in command.go, the server registers as the experimental-mcp subcommand and exposes three primary tools that wrap OSV-Scanner's core functionality. Unlike the standard CLI interface, this integration enables bidirectional communication with AI systems, allowing them to trigger scans, cache results, and retrieve detailed vulnerability metadata on demand.

Available MCP Tools and Capabilities

The server implements three distinct MCP tools registered via mcp.AddTool in cmd/osv-scanner/mcp/command.go:

scan_vulnerable_dependencies

This tool executes a standard OSV-Scanner analysis against specified directories. The handleScan function wraps osvscanner.DoScan, caches discovered vulnerabilities in a thread-safe map, and returns formatted text output suitable for LLM consumption. It accepts parameters for recursive scanning, path globbing, and ignore patterns.

get_vulnerability_details

Given an OSV vulnerability ID (e.g., GO-2023-1558), the handleVulnIDRetrieval function returns the full JSON representation of the advisory. The implementation checks a global vulnerability cache (protected by vulnCacheMu) before querying the OSV-dev API, then marshals the protobuf data into pretty-printed JSON for client consumption.

ignore_vulnerability

The handleIgnoreVulnerability function returns embedded markdown documentation (configuration-instructions.md) that instructs LLMs on how to generate proper ignore-files for OSV-Scanner. This enables automated remediation workflows where AI agents can suppress false positives programmatically.

Architecture and Source Implementation

The MCP implementation resides in cmd/osv-scanner/mcp/command.go and follows a structured server pattern:

1. Server Initialization: Creates mcp.NewServer with the OSV-Scanner name and version
2. Tool Registration: Binds handler functions to MCP tool names using mcp.AddTool
3. Prompt Registration: Exposes a predefined scan_deps prompt to provide LLM context
4. Transport Selection: Switches between mcp.StdioTransport (default) and SSE mode via the --sse flag

The vulnerability cache mechanism uses a global map[string]*osvschema.Vulnerability protected by an RWMutex (vulnCacheMu), ensuring that repeated calls to get_vulnerability_details for the same vulnerability ID do not trigger redundant API requests.

How to Run the MCP Server

STDIO Mode (Default)

STDIO mode communicates over the process' standard input and output, ideal for local LLM integrations:

osv-scanner experimental-mcp

The process reads MCP JSON-RPC requests from stdin and writes responses to stdout.

SSE Mode (Networked)

SSE mode enables remote access by creating an HTTP server with mcp.NewSSEHandler:

osv-scanner experimental-mcp --sse localhost:8080

This listens on http://localhost:8080/sse for MCP clients, allowing centralized scanner instances to serve multiple remote LLM backends.

Client Integration Examples

The integration test in cmd/osv-scanner/mcp/integration_test.go demonstrates the exact client implementation. Below is a practical Go example connecting via SSE:

package main

import (
	"context"
	"log"

	"github.com/modelcontextprotocol/go-sdk/mcp"
)

func main() {
	// Connect to MCP server via SSE
	transport := &mcp.SSEClientTransport{
		Endpoint: "http://localhost:8080/sse",
	}
	client := mcp.NewClient(&mcp.Implementation{
		Name:    "my-client",
		Version: "1.0.0",
	}, nil)

	sess, err := client.Connect(context.Background(), transport, nil)
	if err != nil {
		log.Fatalf("connect error: %v", err)
	}
	defer sess.Close()

	// Scan vulnerable dependencies
	scanRes, err := sess.CallTool(context.Background(), &mcp.CallToolParams{
		Name: "scan_vulnerable_dependencies",
		Arguments: map[string]any{
			"paths":                []string{"./my-project"},
			"recursive":            true,
			"ignore_glob_patterns": []string{},
		},
	})
	if err != nil {
		log.Fatalf("scan error: %v", err)
	}
	log.Printf("Scan output:\n%s", scanRes.Content[0].(*mcp.TextContent).Text)

	// Retrieve specific vulnerability details
	detailRes, err := sess.CallTool(context.Background(), &mcp.CallToolParams{
		Name: "get_vulnerability_details",
		Arguments: map[string]any{
			"vuln_id": "GO-2023-1558",
		},
	})
	if err != nil {
		log.Fatalf("details error: %v", err)
	}
	log.Printf("Vuln JSON:\n%s", detailRes.Content[0].(*mcp.TextContent).Text)
}

The client sends JSON payloads matching the input structs defined in command.go (scanVulnerableDependenciesInput and getVulnerabilityDetailsInput), receiving responses wrapped in mcp.TextContent containers.

Summary

• The OSV-Scanner MCP integration provides LLM-accessible vulnerability scanning via the experimental-mcp subcommand in cmd/osv-scanner/mcp/command.go.
• Three tools expose core functionality: scan_vulnerable_dependencies, get_vulnerability_details, and ignore_vulnerability.
• Dual transport support includes STDIO for local integration and SSE (--sse flag) for networked deployments.
• Built-in caching via vulnCacheMu prevents redundant API calls when retrieving vulnerability details.
• Integration tests in integration_test.go provide working examples of client-server communication.

Frequently Asked Questions

What is the Model Context Protocol (MCP)?

The Model Context Protocol is a lightweight JSON-RPC specification that standardizes how LLM-driven tools communicate with external services. In OSV-Scanner, it enables AI assistants to execute scans and retrieve vulnerability data through structured requests rather than parsing command-line output.

Is the MCP server in OSV-Scanner production-ready?

No, the MCP server is explicitly marked as experimental in the source code and documentation. The implementation in cmd/osv-scanner/mcp/command.go and the associated docs/experimental.md file indicate that APIs and transport mechanisms may change in future releases.

How does vulnerability caching work in the MCP implementation?

The server maintains a global map[string]*osvschema.Vulnerability protected by an RWMutex named vulnCacheMu. When scan_vulnerable_dependencies runs, discovered vulnerabilities populate this cache, allowing get_vulnerability_details to serve subsequent requests for the same OSV ID without querying the remote OSV-dev API.

Can I integrate this with Claude, Gemini, or other LLM assistants?

Yes, any MCP-compatible client can connect to the OSV-Scanner server. For STDIO mode, configure your LLM tool to spawn osv-scanner experimental-mcp as a subprocess. For SSE mode, point the client to the HTTP endpoint specified with the --sse flag (e.g., http://localhost:8080/sse). The protocol is transport-agnostic and works with any MCP-compliant implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}