Versions & Snapshots

Versions and snapshots are the core concepts behind MCP Hub’s certification model. Each version represents a specific commit of an MCP server’s source code, and each snapshot captures an immutable record of the security analysis performed on that version. Together, they create an auditable chain of evidence for every MCP server.

Version Lifecycle

When MCP Hub detects a new commit on a monitored repository (via polling or webhook), it creates a new version. The version progresses through a series of statuses:

PENDING_ANALYSIS --> INGESTING --> INGESTED --> ANALYZING --> CERTIFIED
                                                          \-> FAILED
                                                          \-> KNOWN_VULNERABLE
                                                          \-> DEPRECATED

Key Lifecycle Stages

1. PENDING_ANALYSIS: The version has been created and is waiting to be picked up by the worker.
2. INGESTING: The worker is cloning the repository at the specific commit hash and uploading the source tarball to S3 storage.
3. INGESTED: The source code has been stored. An ANALYZE_VERSION job is queued.
4. ANALYZING: The analysis worker is running the security toolchain (MCP-Scan and optionally Trivy for SBOM generation) against the source code.
5. CERTIFIED: Analysis is complete. Findings have been mapped to controls, scores have been calculated, and an immutable security snapshot has been created.

Terminal States

• FAILED: The ingestion or analysis process encountered an error that could not be resolved after all retry attempts. Check the job logs for details.
• KNOWN_VULNERABLE: A previously certified version has been flagged because new vulnerability data indicates it contains known security issues. The version remains downloadable according to organization policies.
• DEPRECATED: The version has been superseded by a newer release. It can still be downloaded per policy, but it is no longer recommended.

Version Identification

Each version is tied to a specific Git commit hash. The human-readable version identifier follows this format:

commit-<shortHash>-<YYYY-MM-DD>

For example: commit-a3f91c2-2026-01-12

If the repository has Git tags, those tags are displayed as aliases. MCP Hub never invents semantic version numbers – it relies on the actual commit hash as the source of truth.

Security Snapshots

A security snapshot is an immutable record of a security assessment for a specific version. Snapshots are never updated – if a version needs to be re-assessed, a new snapshot is created and linked to the previous one.

What a Snapshot Contains

Each snapshot stores:

Scores (0-100):

• Global Score: A weighted composite of the three sub-scores (Security 50%, Supply Chain 30%, Maturity 20%).
• Security Score: Evaluates vulnerabilities, exposed secrets, and insecure code patterns.
• Supply Chain Score: Evaluates dependency health, licenses, lockfile presence, and pinned dependencies.
• Maturity Score: Evaluates documentation, tests, CI/CD configuration, and project structure.

Findings:

• Raw findings from the analysis tools, categorized by severity (critical, high, medium, low).
• Stored as normalized JSON in S3 with a reference key in the snapshot record.
• Total count and per-severity breakdown are available directly in the snapshot metadata.

Controls:

• Each finding is mapped to a stable, semantic control identifier (e.g., SECRET_EXPOSED, KNOWN_VULNERABLE_DEPENDENCY_CRITICAL, NO_LOCKFILE).
• Controls are tool-agnostic – the same control ID is used regardless of which analysis tool detected the issue.
• Each control result records whether it passed or failed, its severity, a descriptive message, and references to supporting evidence.

Versioning Metadata:

• toolchain_version: The exact versions of all analysis tools (e.g., mcp-scan:1.0.0,trivy:0.50.1).
• scoring_version: The version of the scoring algorithm applied.
• controls_catalog_version: The version of the controls catalog used for mapping findings.

This metadata ensures that any snapshot can be reproduced or understood in the context of the toolchain that produced it.

Snapshot Immutability

Snapshots follow these rules:

• A snapshot is never modified after creation. There is no updated_at field.
• Re-evaluation creates a new snapshot, linked to the previous one via previous_snapshot_id.
• The snapshot chain provides a complete history of how a version’s security posture has been assessed over time.
• All scoring is deterministic: the same inputs with the same toolchain and scoring version will always produce the same scores.

Findings and Controls

Findings

Findings are the raw results produced by the analysis toolchain. They include:

• Vulnerability identifiers (CVEs).
• Exposed secrets and credentials.
• Insecure code patterns.
• Dependency issues (unpinned, vulnerable, unlicensed).
• Missing lockfiles or build configurations.

Findings are stored as detailed JSON in S3 for full traceability. The snapshot record itself contains summary counts by severity for quick reference.

Controls

Controls are stable, semantic identifiers that abstract findings away from specific tools. Examples include:

Each control result in a snapshot includes:

• Passed/Failed: Whether the control check succeeded.
• Severity: Critical, high, medium, or low.
• Message: A human-readable explanation.
• Evidence References: Links to the specific findings that triggered this control.

Controls are versioned through the controls catalog. When the catalog is updated with new controls or refined mappings, re-evaluation creates new snapshots using the updated catalog.

PDF Reports

Enterprise organizations can generate auditable PDF reports for any snapshot. These reports are designed for compliance reviews, security audits, and stakeholder communication.

Report Contents

A PDF report includes:

• Executive Summary: High-level overview with scores and certification level.
• Technical Detail: Complete breakdown of all findings and control results.
• Score Breakdown: Detailed view of how each sub-score was calculated.
• Failed Controls: List of controls that did not pass, with evidence.
• Toolchain References: Exact versions of all tools and scoring algorithms used.
• Legal Disclaimer: Clarification of the scope and limitations of the assessment.

Generating a Report

From the version detail page, click Generate PDF Report, or use the API:

POST /api/v1/orgs/{orgId}/reports

{
  "snapshot_id": "snapshot-uuid",
  "format": "PDF"
}

Report generation is asynchronous – the report is created by a background worker and stored in S3. You can check the status and download the report once it is complete:

GET /api/v1/orgs/{orgId}/reports/{reportId}.pdf

Comparing Versions

MCP Hub enables comparison between versions of the same MCP to understand how the security posture has changed over time:

• Score Trends: View how the global, security, supply chain, and maturity scores have evolved across versions.
• Findings Diff: The snapshot detail page shows the previous snapshot’s scores alongside the current one, making it easy to identify regressions or improvements.
• Control Changes: Compare which controls passed or failed between snapshots to understand what changed.

When a new snapshot is created (either from a new version or from re-evaluation), the previous_snapshot_id field links it to the prior assessment, enabling a chain of comparisons that traces the complete history of the MCP’s security evolution.