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.ai 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, vendor or privacy review, use CertScore.ai MCP Light for the public URL I provide. Use Hosted OAuth when workspace history or private reports are needed. Reuse a suitable retained result unless I request fresh observations. Poll active scans at the returned interval, then summarize the bundle with findings, coverage and report link. Inspect task-relevant workpapers when needed. 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.ai 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.ai 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.ai 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.ai 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.ai 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 60 new scans per session per UTC day, subject to a 100-scan requester-IP limit and a shared 200-scan Light limit. Rolling 10-minute limits are 20 per session, 30 per requester IP and 60 across Light. Reused eligible results do not consume quota. For ongoing scanning, optional free Hosted OAuth links activity to your account and keeps workspace history; existing allowances apply.

Ask me for the public website URL I want to review, and wait for my reply. Then use CertScore.ai to scan only that URL within existing access limits, allowing an eligible recent result to be reused. Request a fresh scan only if I explicitly ask. Retrieve the completed CertScore.ai report and check returned versus total findings and truncation. Recover missing findings with supported bounded retained-report reads for the same scanId, following returned byte-budget guidance and cursors within access limits; use at most five evidence pages and stop on completion, unavailable data or errors. Never start a new scan to fill report gaps. State any findings still unavailable. Group overlapping findings and give three distinct evidence-linked next actions when supported, or fewer if evidence is insufficient. Keep network-request timing, cookie snapshots, new cookie-write timing, completed consent clicks and confirmed consent decisions separate. Include fresh versus reused provenance (or unknown), original scan time, target, region, scope, material coverage limits and the report link. Results are observations, not legal conclusions.

Supply the public URL you want to review. Check finding completeness before the first answer, using bounded reads of the same retained report when needed.

CertScore.ai 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.

Light supplies the scan workflow in its tool descriptions and optional certscore://project-instructions resource. The completed bundle offers an evidence index and relevant follow-ups. Summarize whether the result was new or reused. The first review includes evidence-linked next actions. Ask for a deeper remediation checklist, tracking export, another user-selected site, or a later fresh recheck using the retained baseline scan ID.

CertScore.ai 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.ai 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.

For a focused question, use the existing scan ID with section=consent, gpc, policy, tracking, transport, or forms. Keep the selected section with every cursor. Shared scan, score, findings and coverage context stays included; unselected or not-returned fields do not establish absence. Use workpaper=tracking separately for starting-page JSON/CSV exports.

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, inspect recommendedNextAction. Increase maxBytes within the Light ceiling only when needed, or page through retained report evidence.
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.ai 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.ai tools. Read certscore://example-report if resources are supported; otherwise call certscore_get_scan_bundle with scanId=9ba99a8c-b1ad-44c1-985f-92cef760ab40. Report the retained example’s original date and coverage. If unavailable, report that; do not create a new scan to test the connection.

Connection verification succeeds when the four Light tools are listed without an authorization page and the retained example can be retrieved with its original date and coverage. If the historical example is unavailable, report that without starting a replacement scan.

Anonymous scanning stays free. Free Hosted OAuth offers 100 new scans per rolling 24 hours, up to 20 per rolling hour per active workspace, outside the shared anonymous allowance. No paid plan is required. Your MCP activity is linked to your account.

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

Create a free CertScore.ai account, then connect Hosted OAuth. Authentication is optional and does not reset active quotas.

This Cursor configuration is an example. End-to-end compatibility has not been verified for this release. Use one connection named CertScore.ai 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.ai 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.ai 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.