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:

```bash
cd compliance-mcp
cargo run
```

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

```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:

```bash
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.

```bash
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"`:

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

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

```json
{
  "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.
:::