McpVal 1.1.24

MCP Validator (mcpval)

Validate that an MCP server is safe and usable for AI agents. MCP Validator checks protocol compliance, security posture, AI safety, and operational readiness, then produces a trust assessment plus shareable artifacts for engineering and governance workflows.

Distribution Channels

Install

Install from NuGet:

dotnet tool install --global McpVal
mcpval --help

Or download a self-contained executable from Releases if you do not want a local .NET runtime.

For container-based environments:

docker run --rm ghcr.io/navalerakesh/mcp-validation-security:latest --help

Each GitHub release includes SHA-256 checksums plus an SPDX SBOM for the standalone binaries. NuGet, npm, and GHCR publishes include provenance and SBOM metadata.

Run Your First Validation

Validate a remote MCP endpoint:

mcpval validate \
  --server https://example.test/mcp \
  --access public \
  --output ./mcp-reports

Validate an authenticated server and interpret the result for all documented client profiles:

mcpval validate \
  --server https://example.test/mcp \
  --access authenticated \
  --token "$MCP_TOKEN" \
  --output ./mcp-reports

Validate a local STDIO server:

mcpval validate \
  --server "npx -y @modelcontextprotocol/server-everything" \
  --access public \
  --output ./mcp-reports

validate and health-check support STDIO targets today. discover is currently HTTP-first and returns a clear not-supported error when pointed at a STDIO command.

CLI Surface

validate

Runs the full suite across protocol, tools, prompts, resources, security, and performance.

Client profile evaluation is a host-side interpretation layer. It consumes the neutral validation evidence from the run without changing the underlying findings. validate includes that interpretation by default; use --client-profile only when you want a smaller subset of host profiles.

The standard artifact set is:

• mcp-validation-<timestamp>-report.md - full Markdown report with compact action hints
• mcp-validation-<timestamp>-report.html - full HTML report for sharing
• mcp-validation-<timestamp>-result.json - canonical machine-readable validation object
• mcp-validation-<timestamp>-results.sarif.json - SARIF findings feed for CI and code scanning
• mcp-validation-<timestamp>-audit.json - execution audit manifest for the run

When client profile evaluation is enabled, validate also writes mcp-validation-<timestamp>-profile-summary.json with per-profile compatible, warning, and incompatible counts.

The HTML report opens on the decision surface: Run Status, Deterministic Verdict, and Trust Level. The deterministic verdict drives release gating, while the trust level remains the weighted L1-L5 posture for human review and trend tracking.

When experimental model evaluation is enabled, validate writes mcp-validation-<timestamp>-model-evaluation.json as a separate companion artifact. The canonical *-result.json file remains deterministic and does not embed experimental model output. --enable-model-eval now fails fast when no provider is configured; this build currently includes the deterministic companion provider builtin-rubric.

Other Commands

• mcpval health-check - fast connectivity and initialization probe with auth hints; supports the same --dry-run, host allowlist, and persistence controls as validate
• mcpval discover - capability snapshot for remote endpoints in JSON, YAML, or table form; supports the same --dry-run, host allowlist, and persistence controls as validate
• mcpval report - offline rendering from a saved JSON result or Markdown report path into html, xml, sarif, or junit
• mcpval --list-spec-profiles - list embedded protocol profiles supported by the current build

Example offline rendering:

mcpval report \
  --input ./mcp-reports/mcp-validation-20260421-031745-result.json \
  --format junit \
  --output ./mcp-reports/mcp-validation-20260421-031745.junit.xml

Use --report-detail minimal on either validate or report when you only want the executive view.

GitHub Actions

When mcpval runs inside GitHub Actions, it writes a step summary and emits workflow annotations automatically. The repository root also includes a reusable composite action.

Use a release tag instead of main. The release workflow publishes immutable v<major>.<minor>.<patch> tags and keeps v<major> plus v<major>.<minor> aliases current for the action entrypoint.

name: Validate MCP Server

on:
  pull_request:
  workflow_dispatch:

jobs:
  validate-mcp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate MCP server
        uses: navalerakesh/mcp-validation-security@v1
        with:
          server: https://example.test/mcp
          access: authenticated
          token: ${{ secrets.MCP_TOKEN }}
          policy: strict
          output-dir: ./mcp-validation-results

The composite action installs the published McpVal tool, runs mcpval validate, writes the standard artifact set, and uploads the output directory by default.

Once a tagged release is published, the same root action can be listed in GitHub Marketplace from the release page. That Marketplace entry is only for the GitHub Action surface. The same release still publishes the CLI and companion artifacts to NuGet, npm, GHCR, and GitHub Releases.

Why Teams Use MCP Validator

• Weighted trust assessment with hard caps for critical blockers such as confirmed security failures or MCP MUST failures
• RFC 2119 compliance tiers that distinguish MUST, SHOULD, and MAY semantics
• AI safety analysis covering schema quality, destructive actions, exfiltration risk, and error quality for self-correcting agents
• Real auth and security testing against the target surface instead of purely static metadata review
• Structured findings with stable rule IDs, remediation guidance, and machine-readable outputs for CI workflows
• Shared evidence model that can be interpreted against documented client profiles without forking validator logic

MCP Trust Levels

Every validation run scores four dimensions: Protocol Compliance, Security Posture, AI Safety, and Operational Readiness.

Trust level is determined by a weighted multi-dimensional score and then capped by confirmed blockers such as critical security failures or MCP MUST failures.

Trust level is intentionally separate from the deterministic verdict. Use the deterministic verdict and policy outcome for release gating; use the L1-L5 trust level to summarize overall protocol, security, AI-safety, and operational posture.

Architecture

MCP Validator follows a clean boundary model:

• Mcp.Benchmark.Core holds neutral domain models and abstraction contracts.
• Mcp.Benchmark.ClientProfiles maps neutral evidence onto documented host expectations.
• Mcp.Benchmark.Infrastructure owns transport, auth, validators, scoring, and reporting.
• Mcp.Benchmark.CLI is the composition root and command host.
• Mcp.Compliance.Spec vendors protocol schemas and version metadata.

See docs/Design/Architecture.md for the high-level system view and docs/Design/TechnicalArchitecture.md for the internal lifecycle and extension points.

Build From Source

git clone https://github.com/navalerakesh/mcp-validation-security.git
cd mcp-validation-security
dotnet build
dotnet run --project Mcp.Benchmark.CLI -- --help

Documentation

• docs/README.md - documentation index
• QUICKSTART.md - fast path to the first successful run
• docs/FeatureMatrix.md - current command surface and support boundaries
• docs/Troubleshooting.md - operational troubleshooting guide
• docs/Design/Architecture.md - high-level architecture and runtime flow
• docs/Design/ComponentDesign.md - component responsibilities and interactions
• docs/Design/ForwardArchitecturePlan.md - target-state boundary roadmap
• docs/Design/Schemas.md - schema registry and version-management model
• docs/Resources/GitHub-MCP-Remote-Run.md - representative remote validation run
• CHANGELOG.md - release-facing history

Contributing

• Follow the workflow in CONTRIBUTING.md.
• Run dotnet test before opening a pull request.
• Update the relevant user-facing documentation whenever product behavior changes.

License

Distributed under the MIT License.