MCP server

Connect your agent to https://mcp.certscore.ai/mcp to scan public websites, retrieve reports and access previous scans. Members of active CertScore.ai workspaces can connect through registered OAuth clients with scan:read, scan:create and mcp scopes, across workspace plans, without a manual CertScore access grant. Existing usage limits and public-target restrictions apply.

1. Add the Hosted OAuth endpoint in your agent’s connectors settings. Use the Cursor configuration below when connecting Cursor.
2. Start Connect in your MCP client and sign in to CertScore.ai if prompted. For an unfamiliar client, review its exact connection destination and access, then select Connect or Cancel. Verified integrations and previously approved connections can reconnect without this extra step. Your client may show its own connection and tool-approval prompts.
3. Ask: Use CertScore to scan https://your-site.com and summarize the score, coverage, findings and report link.

The agent should call certscore_scan_site, poll certscore_get_scan_status at the returned interval, then read certscore_get_scan_bundle. Reuse your existing connection to this endpoint instead of installing duplicate namespaces.

Hosts that support MCP prompts and resources can discover these alongside the scan/report tools. If your host displays tools only, paste the instructions below into its chat.

Optional project instructions

When I request a launch or privacy review, use CertScore Hosted OAuth for the public URL I provide. Reuse a suitable retained result unless fresh observations are needed. Poll active scans at the returned interval, then summarize the bundle with findings, coverage and report link. Do not run unsolicited or scheduled scans.

Save this in your project instructions only if you want that workflow. MCP resource: certscore://project-instructions; prompt: certscore_launch_review.

Compare retained scans

Compare CertScore scan [BEFORE_SCAN_ID] with [AFTER_SCAN_ID]. Fetch both bundles without creating a scan. Verify target, region, timestamps and coverage match. Summarize newly returned, persistent and no-longer-returned finding IDs. A finding missing from a later scan is not proof of resolution. Include both report links and limitations.

Prompt: certscore_compare_scans, with beforeScanId and afterScanId.

Turn findings into a checklist

Ask for a proposed remediation checklist for your scan ID, with finding IDs, evidence links, suggested owner roles and manual verification steps. The certscore_remediation_checklist prompt uses retained findings; it does not modify your website or certify that a fix worked.

Call certscore_get_connection_status (or read certscore://connection) for current credential status, workspace access, create permission, remaining rolling quota and a recovery action. It creates no scan. The equivalent authenticated API is GET /api/v2/auth/check?diagnostics=1. Quota is a snapshot, not reserved capacity.

Use your existing connector to reconnect when access expires, is revoked or needs additional scopes. Request scan:read scan:create mcp. An existing sign-in session may be reused; token refresh does not add scopes. A quota limit needs time to reset, not reauthorization.

Cursor: open MCP settings and use the existing CertScore entry. MCP recovery resource: certscore://reconnect. Workspace eligibility applies independently of host permission prompts.

This is an existing ErgoVeritas example, not a current scan of your website. The retained scan completed on September 12, 2026 at 20:26 UTC with partial coverage. Open the report for its score and detailed coverage limitations. It may be historical or unavailable; opening it does not request a fresh scan.

MCP resource: certscore://example-report. Agents must preserve the report’s original timestamps and coverage and never substitute invented example results.

Use a completed scan ID to review retained evidence. The scan bundle includes privacyAuditSummary and GPC facts when available. For an inventory or export request, retrieve the tracking workpaper with the same scan ID.

Review CertScore scan [SCAN_ID] with a CCPA/CPRA focus. Use the retained bundle. Lead with observed GPC delivery, site-recorded opt-out state and tracking activity where returned, including baseline/GPC request counts and their matched duration. Include observed Do Not Sell/Share controls and notice topics. Preserve the actual scan origin and existing score.

Export the tracking inventory for CertScore scan [SCAN_ID]. Use certscore_get_report_evidence_page with workpaper="tracking" and return its JSON and CSV download links. Use the existing scan; preserve workpaper="tracking" with any pagination cursor.

The workpaper covers the starting page. download.url returns JSON and download.csvUrl returns the inventory CSV. Private links expire after five minutes; keep them confidential and request a fresh link after expiry. Existing workspace/public access rules and read quotas apply.

GPC facts can remain available when the paired comparison is indeterminate. Completed Accept/Reject execution and confirmed consent are separate results. Summarize returned after-click facts, and use canonical findings for score effects.

Refresh an older integration

Hosted users keep the same endpoint. If the client still shows an older tool definition, refresh its tool list or reconnect the existing connection. Local npm users can update the package below and restart their MCP process. SDK users can follow the SDK examples.

npm install -g @certscore/[email protected]

Use certscore_get_report_evidence_page for the completed, authorized report. Follow pagination.nextCursor or use the returned JSON download link. Form rows retain field metadata, evidence references, coverage and snapshot status; resolve reportContentRef JSON pointers within the exported document. Full-site reports include their retained additional-page forms after the crawl finishes.

The underlying API is GET /api/v2/scans/{scanId}/report-evidence. Available snapshots are separate JPEG links returned with the evidence, subject to the report’s access rules. Images are not embedded in MCP JSON. Unavailable or withheld images must remain unavailable; do not infer a finding from their absence. The scanner does not fill or submit forms.

Reports provide verified, masked form crops when screenshot capture succeeds; not every detected form has a screenshot. A declared/configured destination is the form action, not evidence that CertScore.ai submitted the form or observed a transfer.

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.

For account-free public scans, use the Light endpoint. Choose Hosted OAuth above to access previous scans in your workspace. Light uses Streamable HTTP and requires no signup, API key, bearer token, browser login, or OAuth, and provides the core workflow through certscore_scan_site,certscore_get_scan_status, andcertscore_get_scan_bundle, plus certscore_get_report_evidence_page for paginated report evidence.

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

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

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.

Use CertScore to scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html. Poll only while the scan is active, then summarize the returned findings, evidence links, scan region and time, coverage limits, and report URL. Treat any pre-consent preview as preliminary and the results as observations, not legal conclusions.

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.

Detailed prompt for tool-driven clients

Use this version when the agent needs explicit rules for previews, retryable responses, and bounded bundle output.

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.

CertScore tools return scan observations and already-projected findings. Use them to answer questions about observed cookies, trackers, consent controls, and retained evidence on a named site; use other sources for general web facts or legal advice.

Scan example.com and summarize pre-consent cookies and trackers. Include the scan region, timestamp, and any coverage limits.
Check whether example.com presented a consent-management surface. Summarize the controls observed on that visit.
For CertScore scan [SCAN_ID], retrieve the report evidence supporting the named finding. Keep the finding ID and evidence references together.

Reject results distinguish confirmed post-refusal evidence from retained after-click observations. Unsupported or unavailable capture remains explicitly limited. Any finding or scoring effect comes from canonical evidence policy.

Scan bundles may include three typed results: postAcceptObservation provides an ordinarily score-neutral comparison baseline, postRefusalObservation reports bounded Reject evidence, and gpcResponse is a jurisdiction-neutral comparison with scoreEffect: none. GPC v3 also includes gpcResponse.observation: bounded capture, current CMP-recorded sale/sharing state, and direct request findings. Its completion is independent of the paired comparison and does not mean GPC was honored. Count execution.status values succeeded and succeeded_with_confirmation as completed paths; report confirmation separately. Registered paths may omit afterAction. Accept/Reject afterAction summaries retain observed click and capture facts even when registration is unconfirmed. Request counts do not classify every request as tracking. A terminal scan status describes lifecycle only.

OAuth and Light both expose certscore_get_report_evidence_page. Start with scanId, then pass pagination.nextCursor as cursor until pagination.complete is true. Entries carry JSON Pointer paths and values; oversized strings have numbered parts. Keep one snapshot and restart if it changes. Use the scan bundle for concise summaries.

A complete export preserves the report’s findings, evidence tables and limitations; it does not mean the scan observed everything. Full-site exports also include additional-page forms and fields, page and resource inventories, services, and available snapshot download URLs. Full-report downloads may use confidential, short-lived report-only links returned by the tool; do not publish or log those links or attach OAuth credentials to them. If the host cannot download a file, continue via nextCursor. Separate workspace image downloads require the OAuth bearer credential. Raw artifacts outside the report and inline image bytes are excluded. Light reads eligible public scans; OAuth also reads reports in the authorized workspace.

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, certscore_get_scan_bundle, and certscore_get_report_evidence_page 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 the four 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, access to previous scans or advanced diagnostic tools with self-serve OAuth access.

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

This Cursor configuration is an example. End-to-end compatibility has not been verified for this release. Use one connection named CertScore Hosted OAuth. The public client ID is not a secret. Follow the connection prompts in your client and sign in to CertScore.ai if requested. Client support is verified separately from the model selected inside a host.

{
  "mcpServers": {
    "CertScore Hosted OAuth": {
      "url": "https://mcp.certscore.ai/mcp",
      "auth": {
        "CLIENT_ID": "certscore_cursor_hosted_oauth_v1",
        "scopes": ["scan:read", "scan:create", "mcp"]
      }
    }
  }
}

Merge into .cursor/mcp.json or ~/.cursor/mcp.json. Reuse an existing connection to the same endpoint. Light at /mcp/light supports public scans but has no previous workspace scans. The canonical sequence is certscore_scan_site → certscore_get_scan_status while active → certscore_get_scan_bundle. Report score, coverage, finding IDs, pre-consent observations, and the report URL.

For dynamic registration, use a stable descriptive client_name identifying the host and integration. Names are client-declared labels, not verified identity. Independent hosts must use their documented configuration format; AddMcpServer is not a portable MCP protocol operation.

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 workspaces connecting through supported OAuth clients receive the hosted scope under the active-workspace OAuth policy. Local API 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.