cleanlib-mcp-server 0.5.4

CleanLibrary MCP server — exposes verdict-aware supply-chain risk assessment as Model Context Protocol tools for AI agent workflows

cleanlib-mcp-server

CleanLibrary MCP (Model Context Protocol) server — gives AI agents (Claude Code, Claude Desktop, Cursor, etc.) read access to CleanLibrary's library-verdict + vulnerability-intelligence APIs. Your agent can call cleanlib_fetch_verdict to ask "should we use lodash@4.17.20?" and get a structured response with verdict tier (ALLOW / WARN / DENY), CVE references, fix recommendations, and KMS-signed attestation.

Install

pip install cleanlib-mcp-server

Latest: 0.5.x on PyPI. 14 tools covering verdict / advisories / exploitability / EPSS / KEV / remediation / Vector / bulk operations.

Configure

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cleanlib": {
      "command": "cleanlib-mcp-server",
      "env": {
        "CLEANLIB_ENDPOINT": "https://cleanapp.clnstrt.dev",
        "CLEANLIB_API_KEY": "clk_YOUR_BEARER_HERE",
        "CLEANLIB_ENRICH_BEARER": "clk_YOUR_BEARER_HERE"
      }
    }
  }
}

Restart Claude Desktop. The 14 tools should appear in the tool picker.

Claude Code

In your .claude/settings.json or via the claude mcp add command:

claude mcp add cleanlib \
  --command cleanlib-mcp-server \
  --env CLEANLIB_ENDPOINT=https://cleanapp.clnstrt.dev \
  --env CLEANLIB_API_KEY=clk_YOUR_BEARER_HERE \
  --env CLEANLIB_ENRICH_BEARER=clk_YOUR_BEARER_HERE

Cursor / other MCP clients

The server speaks standard MCP over stdio. The same command + env pattern applies — consult your client's MCP server configuration docs for the exact file location.

Bearer provisioning

CleanLibrary uses two bearer scopes:

Bearer	Scope	What it accesses
CLEANLIB_API_KEY	App-side (cleanapp.clnstrt.dev)	cleanlib_fetch_verdict + cleanlib_health_check
CLEANLIB_ENRICH_BEARER	Tricorder substrate (cleanlib-enrich.clnstrt.dev)	12 enrichment tools (advisories, exploitability, EPSS, KEV, remediation, Vector, CVE-enrich, bulk operations)

For most customers these are the same bearer with both scopes; your design-partner / pilot agreement will spell out the tier.

Tier shape

Tier	Sustained	Burst	Typical use case
Free / evaluation	60 req/min	10	Single-developer exploratory probing
Standard	600 req/min	60	CI/CD pipelines + typical team usage
Enterprise	6000 req/min	600	Large-org CI fleet + bulk operations

On rate-limit hit: HTTP 429 + Retry-After: <seconds> header. Honor it.

Provisioning flow

1. Request bearer via your CleanLibrary design-partner / pilot contact at [e-mail]
2. Receive a token of the form clk_<random>_<tier> (e.g. clk_abc...xyz_001 for standard-tier-pilot)
3. Store in your local config file (above) or a secret manager:
   • macOS: Keychain (recommended) or ~/.config/cleanlib/bearer
   • Linux: ~/.config/cleanlib/bearer or your customer-side secret store
   • Cloud/CI: GitHub Actions Secret / GitLab CI variable / AWS SSM / GCP Secret Manager
4. Never commit bearer tokens to a repository. Keep them in environment variables or secret managers.

Tool reference

14 tools post v0.5.0:

Tool	What it does	Tier
cleanlib_health_check	App health + backend honesty block	Any
cleanlib_fetch_verdict	Get verdict envelope for a (ecosystem, package, version)	Any
cleanlib_advisories	List CVE advisories for a package	Any
cleanlib_remediation	Get recommended upgrade-version + remediation paths	Any
cleanlib_exploitability	Per-CVE exploitability assessment	Any
cleanlib_epss	Per-CVE EPSS score (exploitation likelihood)	Any
cleanlib_kev	⚠ Deprecated / fallback — per-CVE CISA KEV listing (wraps the now-410-deprecated /kev/:cve); prefer cleanlib_kev_package or cleanlib_exploitability	Fallback
cleanlib_cve_enrich	Multi-source CVE enrichment	Gated
cleanlib_enrich_package	Full enrichment for a package (cycles all sources)	Standard+
cleanlib_epss_package	EPSS for all known CVEs on a package	Standard+
cleanlib_kev_package	KEV rollup for a package	Standard+
cleanlib_vector_verdict	Tricorder Vector triage verdict	Standard+
cleanlib_exploitability_bulk	Bulk exploitability for many CVEs	Standard+
cleanlib_packages_check_bulk	Bulk verdict check for many packages	Standard+

Verify it works

In Claude Code or Claude Desktop, ask:

"What's the CleanLibrary verdict for npm/lodash/4.17.20?"

The agent should invoke cleanlib_fetch_verdict and return something like:

The verdict is DENY (verdict source: VECTOR_VERDICT, severity HIGH, composite score 81). 5 CVEs affect this version. Top: CVE-2026-4800 (HIGH, CVSS 8.1, fixed in 4.18.0). Recommended action: upgrade to 4.17.21+ to address all 5 CVEs, or to 4.18.0+ for the cleanest path.

If you get AUTH_ERROR or bearer required: double-check the env block in your config file.

If every package returns ALLOW_BY_ABSENCE: your CLEANLIB_ENRICH_BEARER may be missing or scoped wrong. Run cleanlib_health_check — it returns the backend's honest state.

Diagnose bearer configuration

If verdict tools work but enrichment tools (advisories, exploitability, epss, kev, cve_enrich, remediation, bulk variants) return PermissionError or silently produce empty results, the two bearer pools are non-interchangeable and one of them is misconfigured. Run the built-in diagnostic from the same shell that launches your MCP client (so the same env vars are visible):

cleanlib-mcp-server --test-bearers

It probes both pools end-to-end (App /v1/customer/verdicts/... + enrich /api/v1/advisories/...) with whatever CLEANLIB_API_KEY and CLEANLIB_ENRICH_BEARER your environment carries, and reports [OK] / [FAIL] / [SKIP] per pool. Exit code is non-zero if any required bearer is missing or rejected — wire it into your onboarding smoke-check.

Sample agent prompts

These work across Claude Code / Claude Desktop:

• "Check requirements.txt packages against CleanLibrary and flag any DENY."
• "What CVEs affect npm/express/4.17.1?"
• "Should I upgrade lodash from 4.17.20? Show me the upgrade journey."
• "Cross-check python-cryptography/3.4.7 for KEV and EPSS data."

What ships today

• ✅ Rate-limit enforcement — per-minute quotas (above) with HTTP 429 + Retry-After header
• ✅ App-layer caching — vulnerability cross-reference TTL cache (5-min default) with as_of honesty (cache-hit responses carry the original substrate-fetch time, not cache-read time)
• ✅ Observability foundation — Cloud Monitoring custom-metrics + availability.degraded_stale honesty signal on verdict envelope
• ✅ KMS-signed attestation — every verdict carries an externally-verifiable ECDSA-P256 signature anchored at cleanlibrary-prod KMS

What's NOT shipped yet (honest gaps)

• Per-route SLA differentiation — single Cloud Run service handles all routes today; per-route quotas land cycle-16
• Full availability block population — schema present + degraded_stale live; kev / epss / exploitation_fusion sub-fields land cycle-16
• Multi-region — single us-central1; EU sovereign deployment is a BD-trigger
• Self-hosted enrich-api offering — hosted-only today; air-gap customers contact [e-mail]

Run

cleanlib-mcp-server   # stdio transport (per MCP spec)

Backend modes

• Connected — when CLEANLIB_ENDPOINT + CLEANLIB_API_KEY are set, the server queries your CleanLibrary deployment for live verdicts.
• Local fixtures — when no endpoint is configured (or the configured endpoint is unreachable), the server returns bundled demo fixtures so MCP clients always receive useful output during local development.

Troubleshooting

Symptom	Likely cause	Fix
Extension 'cleanstart.cleanlibrary' not found in Cursor	Open VSX republish pending; Cursor uses Open VSX	Install via direct .vsix from VS Code Marketplace
ALLOW_BY_ABSENCE for every package	Tricorder substrate gap for that package set	Cross-check via cleanlib_advisories separately; verdict is honest "no findings on file" not "verified clean"
Internal error during session validation 500	Stale auth middleware (pre-2026-06-06)	Update to latest cleanlib-mcp-server 0.5.x
Timeout on cleanlib_fetch_verdict	Upstream Tricorder degraded	Check cleanlib_health_check for backend.vector_client state
HTTP 429 / rate_limit_exceeded	Hit tier's per-minute quota	Honor the Retry-After header (seconds-until-token-refill); see "Tier shape" above

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests
pytest -v

Feedback / contact

• Issues / questions: [e-mail]
• Source: https://bitbucket.org/triamsec/cleanlib-mcp-server

License

Proprietary. See LICENSE for terms. © 2026 CleanStart Inc.