@certscore/mcp

CertScore MCP

CertScore MCP exposes a focused Model Context Protocol server for CertScore Pulse workflows.

Status: public developer preview. The server is distributed for external macOS MCP clients through Homebrew. Local WC01 development uses pnpm mcp:certscore.

Public docs:

• https://certscore.ai/developers/mcp
• https://certscore.ai/developers/quickstart
• https://certscore.ai/developers/reference
• https://certscore.ai/api-pulse

Tools

• scan_site - Start or reuse a CertScore public-web scan for a public URL.
• get_scan - Retrieve the API v2 public-safe scan resource for a stable scan ID.
• get_scan_status - Pass scanId (preferred, API v2). Pass jobId only for a just-created scan that has not yet returned a scanId.
• get_report - Retrieve a summary CertScore Pulse report by stable scan ID. Use get_evidence for the larger bounded evidence packet.
• get_evidence - Retrieve the bounded structured Evidence JSON packet for a stable scan ID. Excludes raw cookie values, raw bodies, sensitive payloads, full DOM, and unredacted query values.
• export_findings - Return structured findings from a CertScore Pulse report for downstream review or ticketing workflows.
• list_findings - List API v2 public-safe findings already projected for a scan.
• get_pre_consent_cookies_trackers - Retrieve the public-safe Cookies & Trackers (Pre-consent) report table as compact JSON for a scan.
• explain_finding - Explain a single CertScore finding with public evidence, caveats, and reviewer next steps.
• get_latest_domain_scan - Retrieve the latest eligible API v2 public-safe scan for a domain.
• get_latest_domain_pre_consent_cookies_trackers - Retrieve the public-safe Cookies & Trackers (Pre-consent) table from the latest eligible scan for a domain.

The initial MCP surface intentionally does not include account scan browsing, scan comparison tools, or the removed create_scan compatibility alias.

Configuration

Install with Homebrew on macOS:

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

The cask installs the prebuilt MCP command for users who prefer a persistent local binary.

Use the installed command from an MCP client:

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

Run from this monorepo for local development:

CERTSCORE_API_KEY=... pnpm mcp:certscore

Generate a scoped preview key after applying DB migrations:

pnpm db:migrate
pnpm mcp:certscore:generate-key -- --name "CertScore MCP preview"

Run the built package directly after local build:

CERTSCORE_API_KEY=... certscore-mcp

Optional:

CERTSCORE_BASE_URL=https://certscore.ai
CERTSCORE_REQUEST_TIMEOUT_MS=300000

CERTSCORE_API_KEY should be a scoped CertScore API token for the workspace or preview user. The MCP server passes it to Pulse as a bearer token and does not persist it.

API Key Access

MCP clients usually need scan:read, scan:create, and mcp scopes. Request developer-preview access by emailing [e-mail] with your organization, MCP client, expected workflow, expected request volume, contact email, and requested scopes.

Verify Install

certscore-mcp --version
certscore-mcp --help
CERTSCORE_API_KEY=... certscore-mcp doctor

The doctor command checks binary startup, version output, Node.js runtime compatibility, the configured CertScore base URL, API v2 health, and API key presence. It does not print secrets, create scans, or inspect raw scanner artifacts. There is no dedicated public auth-check endpoint; verify credentials with a real MCP tool call such as scan_site after the client is connected.

MCP Client Examples

Claude Desktop-style config:

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

Cursor config:

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

Windsurf or generic stdio MCP client config:

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

Local repo config for contributors:

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

Agent Workflow

• Call scan_site with a public URL.
• If it returns a jobId, call get_scan_status until the scan completes.
• Call get_scan with the stable scanId.
• Call list_findings to route structured findings into review workflows.
• Call get_evidence when a reviewer or agent needs the larger bounded evidence packet.
• Call get_pre_consent_cookies_trackers when the user asks for Cookies & Trackers (Pre-consent) table data as JSON.
• Call explain_finding when a reviewer needs evidence and caveats for a specific finding.
• Call get_latest_domain_scan or get_latest_domain_pre_consent_cookies_trackers when the user asks for latest eligible public data for a domain.

{
  "tool": "get_pre_consent_cookies_trackers",
  "arguments": {
    "scanId": "00000000-0000-4000-8000-000000000123"
  }
}

{
  "tool": "get_latest_domain_pre_consent_cookies_trackers",
  "arguments": {
    "domain": "example.com",
    "scanFrom": "eu_ie"
  }
}

When summarizing table data, group rows by vendor, purpose, and host unless the user asks for row-level JSON. Treat MCP outputs as automated public-web observations for review. They are not legal advice, certification, or a compliance determination. MCP tools must not infer findings from raw labels, raw network events, missing data, or display-only context.

Live Smoke

CERTSCORE_API_KEY=... pnpm mcp:certscore:smoke

Optional:

CERTSCORE_MCP_SMOKE_URL=https://example.com

Without CERTSCORE_API_KEY, the smoke script exits successfully with a skip message.

For the full production operator smoke, run from the WC01 repo:

pnpm ops:smoke:mcp-production

This verifies the Homebrew-installed certscore-mcp command against live https://certscore.ai. It creates a short-lived preview key, stores only the hash in production through the approved ECS/Fargate path, checks required tools, requests a fresh EU-IR scan with freshness: "refresh" and scanFrom: "eu_ie", requires non-empty findings and pre-consent cookies/trackers rows, runs explain_finding, and revokes the temporary key afterward. It exercises existing public-safe API/MCP projections only.

Troubleshooting

• Command not found: run the Homebrew install again and confirm Homebrew's bin directory is on PATH.
• Missing API key: set CERTSCORE_API_KEY in the MCP client environment and rerun certscore-mcp doctor.
• Bad token: rotate the key or request a scoped API/MCP key from [e-mail].
• API unreachable: check CERTSCORE_BASE_URL and verify https://certscore.ai/api/v2/health.
• Homebrew tap stale: run brew update and reinstall certscore-mcp.
• Old cached release: run brew reinstall --cask certscore-mcp after updating the tap.

Runbook

See docs/certscore-mcp-homebrew-release.md for Homebrew release steps and docs/certscore-mcp-preview-runbook.md for key issuance, smoke testing, deploy verification, and scan-to-report guardrails.