MCP server

Hosted MCP applies the policy before composite tool fan-out, so an over-limit bundle is rejected before it starts its internal API reads. Local MCP receives the same protection from the underlying CertScore API.

First-time agents should use the Light endpoint. It uses Streamable HTTP and requires no signup, API key, bearer token, browser login, or OAuth, and exposes exactly certscore_scan_site,certscore_get_scan_status, andcertscore_get_scan_bundle.

Light:
https://mcp.certscore.ai/mcp/light

Transport: Streamable HTTP
Authentication: None
Tools: certscore_scan_site, certscore_get_scan_status, certscore_get_scan_bundle

Cursor setup

Codex setup

codex mcp add certscore --url https://mcp.certscore.ai/mcp/light

Light allows up to 50 genuinely new scans per UTC day across the public Light surface and 5 per rolling 10 minutes. Reused eligible results do not consume quota.

Scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html. If certscore_scan_site includes preConsentPreview, treat it as a partial preview and continue the workflow. Distinguish captured totals from bounded returned identities; use trackingVendorCount for non-operational tracking vendors and keep operationalVendors separate. Do not compare the compatibility preview trackerCount with the completed inventory's broader trackerCount. Never report preview counts as final totals. If certscore_scan_site returns a queued, running, or finalizing result, retain the returned scanId and poll certscore_get_scan_status using scanId only. If certscore_scan_site returns a retryable error without a scanId, wait for retryAfterSeconds and retry certscore_scan_site; do not call certscore_get_scan_status until a scanId exists. Once the scan reaches a terminal status, call certscore_get_scan_bundle with detail=findings and maxBytes=8000. Summarize whether the result was new or reused, the score, risk level, findings, evidence links, coverage limitations, and report URL. Explain truncation or omitted sections when present. Treat results as automated public-web observations, not legal conclusions, certifications, or compliance determinations.

ErgoVeritas provides stable, owned canary pages suited to demonstrating the complete scan, status, and bundle flow. The canary intentionally contains test signals, so its findings are useful for exercising the API rather than evaluating a production site.

CertScore results are automated observations from a public-web scan. No-go, not-observed, and limited-coverage results are not proof of compliance, absence of risk, or legal status. Review the retained evidence and applicable context before relying on a finding.

Reject Path observations are reported only when the scan has eligible, confirmed post-refusal evidence. Unsupported, unavailable, or limited Reject Path coverage remains explicit and score-neutral.

Scan bundles may include three typed results: postAcceptObservation is a score-neutral comparison baseline, postRefusalObservation is the only one that can support a choice-path finding, and gpcResponse is a jurisdiction-neutral comparison with scoreEffect: none. A terminal scan status describes lifecycle only; the observation verdict carries the outcome, and every non-confirmed observation status is limited coverage rather than a pass.

1. Call certscore_scan_site with a public URL.
2. If a retryable error has no scanId, wait retryAfterSeconds and retry certscore_scan_site.
3. If preConsentPreview is present, summarize it only as preliminary passive observations. It is not a finding, score, or final result.
4. If the result is queued, running, or finalizing, retain scanId.
5. Poll certscore_get_scan_status using scanId only. Never poll until scanId exists.
6. Stop polling at a terminal status, then call certscore_get_scan_bundle.
7. Use detail=findings for a compact finding review.
8. Use detail=evidence for evidence digests and references.
9. If truncated, follow recommendedNextAction or increase maxBytes.
10. Summarize findings together with coverage limitations and the report URL.

certscore_scan_site
→ retry certscore_scan_site if a retryable error has no scanId
→ summarize preConsentPreview only as preliminary context when present
→ certscore_get_scan_status with scanId if still running
→ certscore_get_scan_bundle after terminal status

Recommended bundle budgets:
summary   maxBytes=5000
findings  maxBytes=8000
evidence  maxBytes=8000
full      maxBytes=12000 or higher

A 5,000-byte response prioritizes compact core finding rows over optional inventory and duplicate envelope fields. When repeated per-finding URLs are omitted, use evidenceUrlTemplate with contentUrls.findings and the returned finding ID. Inspect actualBytes, truncated, omittedSections,canonicalFindingsComplete, nextRecommendedMaxBytes, and returned report or evidence content URLs.

Call certscore_get_scan_status only after certscore_scan_site returns a scanId. A retryable response without one must return to certscore_scan_site.

CertScore results are automated observations from a public-web scan. No-go, not-observed, and limited-coverage results are not proof of compliance, absence of risk, or legal status. Review the retained evidence and applicable context before relying on a finding.

List the available CertScore tools and confirm that certscore_scan_site, certscore_get_scan_status, and certscore_get_scan_bundle are available. Then scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html and report whether the result was new or reused.

Success means the tool list contains exactly the three Light tools, no authorization page appears, andcertscore_scan_site returns a stable scanId plus an explicit new-or-reused decision. An eligible reused result reports that quota was not consumed.

Upgrade when you need a dedicated higher-volume allowance, production or team access, backend automation, scan history, advanced diagnostic tools, or support-managed scopes.

Need more scans or advanced tools? Upgrade to Authenticated MCP.

Use this route for local stdio clients, backend automation, or environments where you manage credentials directly. A CertScore account and a scoped key are required.

brew tap ergoveritas1-alt/certscore https://github.com/ergoveritas1-alt/certscore.ai
brew install --cask certscore-mcp

The cask installs a persistent local MCP command for users who prefer Homebrew-managed tools.

The local stdio MCP server works with a self-serve cs_ro_ key carrying pulse:read and mcp. Sign in, verify your email, then request the key from /api/v2/keys/request. Stdio tools that create scans require pulse:scan; hosted OAuth usesscan:create. Active Trial workspaces connecting through Claude receive the hosted scope automatically. Other clients and local keys remain grant-gated at [email protected].

Self-serve read-only MCP key:
1. Sign in at https://certscore.ai/login and verify your email.
2. POST https://certscore.ai/api/v2/keys/request from the signed-in browser session.
3. Use the returned cs_ro_ key as CERTSCORE_API_KEY.

certscore-mcp --version
certscore-mcp --help
CERTSCORE_API_KEY=<token> certscore-mcp doctor
CERTSCORE_API_KEY=<token> certscore-mcp doctor --check-auth

The doctor command checks the installed binary, Node.js runtime compatibility, the configured CertScore.ai base URL, API v2 health, and API key presence without printing the token. Add --check-auth to validate the credential against the API without creating a scan or inspecting raw scanner artifacts.

curl -LO https://github.com/ergoveritas1-alt/certscore.ai/releases/download/certscore-mcp-v{version}/certscore-mcp-v{version}.tar.gz
curl -LO https://github.com/ergoveritas1-alt/certscore.ai/releases/download/certscore-mcp-v{version}/SHA256SUMS
sha256sum --check SHA256SUMS

Release tarballs are built on Linux by GitHub Actions. The published SHA256SUMS file should match the cask checksum.

{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "<token>",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

The server runs over stdio and reads the API key from the MCP client environment. Keep the token scoped and rotate it if it is shared outside your workspace.

{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "<token>",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

• If the command is not found, reinstall the cask or check that Homebrew's bin directory is on PATH.
• If Node.js is not found, make sure the MCP client inherits a PATH containing Node.js and Homebrew's bin directory.
• If the API key is missing, set CERTSCORE_API_KEY in the MCP client environment and rerun doctor --check-auth.
• If a token is rejected, run doctor --check-auth before rotating the key or requesting a scoped API/MCP key from [email protected].
• If API health is unreachable, check CERTSCORE_BASE_URL and verify that https://certscore.ai/api/v2/health loads.
• If Homebrew uses stale metadata, run brew update and reinstall the cask.
• If an old release is cached, run brew reinstall --cask certscore-mcp after updating the tap.

CERTSCORE_API_KEY=<token> pnpm mcp:certscore

{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "<token>",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

{
  "mcpServers": {
    "certscore": {
      "command": "pnpm",
      "args": ["mcp:certscore"],
      "cwd": "/path/to/WC01",
      "env": {
        "CERTSCORE_API_KEY": "<token>",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

Several tools return or reference Pulse, CertScore.ai's compact public report projection for agents. See What is Pulse? for how it relates to scan resources and findings.

API v2 MCP tools return startedAt, completedAt, and scanTimeSeconds when CertScore.ai has enough timing evidence. Treat scanTimeSeconds: null as unavailable rather than zero.

const scan = await certscore_get_scan({ scanId });
const status = await certscore_get_scan_status({ scanId });

// scan.scanTimeSeconds and status.scanTimeSeconds are numbers or null.

Scan, status, report, export, and explanation tools preservecompleted_limited,resultDisposition: no_go, the stable reason code, customer-safe copy, target-site versus scanner-limitation attribution, retry guidance, and a bounded evidence excerpt when retained.

The beginner MCP path ends above. Use these separate developer sections only when you are building a direct HTTP or TypeScript integration.

1. certscore_scan_site with a public URL; a new scan returns its stable scanId and may include a partial preConsentPreview when the runtime lane completes or reaches its six-second checkpoint; otherwise it falls back to the stable scanId alone.
2. Treat preConsentPreview only as partial passive context. Distinguish captured totals from bounded returned identities; use trackingVendorCount for non-operational vendors and keep operationalVendors separate. Never treat it as a finding, score, or final result.
3. certscore_get_scan_status only when certscore_scan_site returns a non-terminal result containing scanId; poll with scanId only.
4. certscore_get_scan_bundle for canonical status, findings, bounded evidence, and pre-consent inventory.
5. certscore_get_report, certscore_get_evidence, certscore_list_findings, or cookie inventory only when a dedicated view is needed.
6. certscore_explain_finding for evidence summaries and caveats.
7. certscore_get_latest_domain_scan or certscore_get_latest_domain_pre_consent_cookies_trackers when the user asks for latest-domain data.

certscore_scan_site reports whether it reused a result, the freshness decision, whether anonymous quota was consumed, the remaining daily allowance, its UTC reset time, and the recommended next tool.

{
  "executionMode": "reused_scan",
  "reused": true,
  "reusedScanAgeSeconds": 90,
  "freshnessDecision": "reused_existing_scan",
  "quotaConsumed": false,
  "anonymousQuotaLimit": 20,
  "anonymousQuotaRemaining": 7,
  "anonymousQuotaResetAt": "2026-07-16T00:00:00.000Z",
  "upgradeSupportEmail": "[email protected]",
  "upgradeMessage": "For a higher-volume allowance, contact [email protected].",
  "recommendedNextTool": "certscore_get_scan_bundle"
}

certscore_get_pre_consent_cookies_trackers({
  scanId: "00000000-0000-4000-8000-000000000123"
})

certscore_get_latest_domain_pre_consent_cookies_trackers({
  domain: "ergoveritas.com",
  scanFrom: "eu_ie"
})

MCP tools return compact public-safe JSON. They must not infer raw-signal findings or convert automated review signals into legal conclusions. CertScore.ai outputs are automated public-web observations for human and agentic review. They are not legal advice, certification, or a compliance determination. Group Cookies & Trackers rows by vendor, purpose, and host when the user wants a short review handoff.