compliance-scanner-agent/docs/features/mcp-server.md

MCP Server

The Model Context Protocol (MCP) server exposes compliance data to external LLMs and AI agents. Any MCP-compatible client — such as Claude, Cursor, or a custom agent — can connect and query findings, SBOM data, and DAST results without direct database access.

How It Works

The compliance-mcp crate runs as a standalone service that connects to the same MongoDB database as the agent and dashboard. It registers a set of tools that LLM clients can discover and call through the MCP protocol.

LLM Client  ──MCP──▶  compliance-mcp  ──MongoDB──▶  compliance_scanner DB

The server supports two transport modes:

Transport	Use Case	How to Enable
Stdio	Local development, piped to a CLI tool	Default (no MCP_PORT set)
Streamable HTTP	Remote deployment, multiple clients	Set MCP_PORT=8090

Available Tools

The MCP server exposes seven tools:

Findings

Tool	Description
list_findings	Query findings with optional filters for repository, severity, status, and scan type. Returns up to 200 results (default 50).
get_finding	Retrieve a single finding by its MongoDB ObjectId.
findings_summary	Get finding counts grouped by severity and status, optionally filtered by repository.

SBOM

Tool	Description
list_sbom_packages	List SBOM packages with filters for repository, vulnerabilities, package manager, and license.
sbom_vuln_report	Generate a vulnerability report for a repository showing all packages with known CVEs.

DAST

Tool	Description
list_dast_findings	Query DAST findings with filters for target, scan run, severity, exploitability, and vulnerability type.
dast_scan_summary	Get a summary of recent DAST scan runs and finding counts.

Running Locally

Stdio Mode

Run the MCP server directly — it reads from stdin and writes to stdout:

cd compliance-mcp
cargo run

Configure your MCP client to launch it as a subprocess. For example, in a Claude Code mcp.json:

{
  "mcpServers": {
    "compliance": {
      "command": "cargo",
      "args": ["run", "-p", "compliance-mcp"],
      "cwd": "/path/to/compliance-scanner"
    }
  }
}

HTTP Mode

Set MCP_PORT to start the Streamable HTTP server:

MCP_PORT=8090 cargo run -p compliance-mcp

The server listens on http://0.0.0.0:8090/mcp. Point your MCP client to this endpoint.

Configuration

Variable	Description	Default
MONGODB_URI	MongoDB connection string	mongodb://localhost:27017
MONGODB_DATABASE	Database name	compliance_scanner
MCP_PORT	Port for HTTP transport (omit for stdio)	—
RUST_LOG	Log level filter	compliance_mcp=info

Create a .env file in the project root or set these as environment variables.

Deploying with Docker

The Dockerfile.mcp builds and runs the MCP server in HTTP mode on port 8090.

docker build -f Dockerfile.mcp -t compliance-mcp .
docker run -p 8090:8090 \
  -e MONGODB_URI=mongodb://mongo:27017 \
  -e MONGODB_DATABASE=compliance_scanner \
  -e MCP_PORT=8090 \
  compliance-mcp

Coolify Deployment

1. Create a new service in your Coolify project
2. Set the Dockerfile path to Dockerfile.mcp
3. Set the exposed port to 8090
4. Add environment variables: MONGODB_URI, MONGODB_DATABASE, MCP_PORT=8090
5. The MCP endpoint will be available at your configured domain under /mcp

The CI pipeline automatically deploys on changes to compliance-core/, compliance-mcp/, Dockerfile.mcp, or Cargo.toml/Cargo.lock. Add the COOLIFY_WEBHOOK_MCP secret to your Gitea repository.

Managing MCP Servers in the Dashboard

Navigate to MCP Servers in the dashboard sidebar to:

• Register MCP server instances with their endpoint URL, transport type, port, and database connection
• View server configuration, enabled tools, and status
• Manage access tokens — reveal, copy, or regenerate bearer tokens for authentication
• Delete servers that are no longer needed

Each registered server is assigned a random access token on creation. Use this token in your MCP client configuration for authenticated access.

Example: Querying Findings from an LLM

Once connected, an LLM can call any of the registered tools. For example:

"Show me all critical findings" triggers list_findings with severity: "critical":

{
  "tool": "list_findings",
  "arguments": {
    "severity": "critical",
    "limit": 10
  }
}

"What vulnerable packages does repo X have?" triggers sbom_vuln_report:

{
  "tool": "sbom_vuln_report",
  "arguments": {
    "repo_id": "683abc..."
  }
}

::: tip The MCP server is read-only — it only queries data from MongoDB. It cannot modify findings, trigger scans, or change configuration. This makes it safe to expose to external LLM clients. :::