Skip to content
CodeCleared Docs
AppFrançais
Published

Last reviewed: 2026-09-30

CodeCleared MCP integration

Connect an MCP client to CodeCleared with local stdio or hosted HTTP, least-privilege scopes, and repository-aware security tools.

Connect your MCP client

Use the @codecleared/mcp-server package for a local stdio server, or connect to the hosted HTTP endpoint at {API_URL}/mcp. Use a least-privilege service token and keep it in your client’s secret store.

In the app, copy ready-made client snippets under Settings → Service tokens → MCP (/settings/service-tokens?tab=mcp). Create tokens on the Tokens tab of the same page.

Local stdio configuration

Install the package in the environment that runs your MCP client, then configure it with your customer API URL and token:

{
  "mcpServers": {
    "codecleared": {
      "command": "npx",
      "args": ["-y", "@codecleared/mcp-server", "stdio"],
      "env": {
        "CODECLEARED_API_URL": "https://api.example",
        "CODECLEARED_TOKEN": "cc_..."
      }
    }
  }
}

Hosted HTTP configuration

Connect your client to {API_URL}/mcp and send Authorization: Bearer cc_.... On hosted HTTP, the available tool list is filtered by the token’s scopes. scan:read is sufficient for reading results; use scan:all to trigger scans or generate SBOMs. Package search and evaluation also require package-finder:read. Policy bundle tools require policy:read (and policy:write / policy:admin to import). Finding triage tools require finding:read or finding:write — not included in scan:all.

Optional repository context

A .codecleared.json file can set a default repository context:

{ "repositoryId": "repository-uuid", "fullName": "owner/repository" }

Use one stable identifier where possible. If both fields are present, confirm they refer to the same repository in the intended organization.

Available tools

All tool names are prefixed with codecleared_.

  • Repository and unit discovery: codecleared_list_repositories, codecleared_resolve_repository, codecleared_list_project_units
  • Work execution: codecleared_trigger_scan, codecleared_generate_sbom, codecleared_get_scan_status, codecleared_wait_for_scan
  • Results: codecleared_get_vulnerabilities, codecleared_get_sbom, codecleared_get_licenses, codecleared_get_secrets, codecleared_get_sast_findings, codecleared_get_scores, codecleared_get_security_reference
  • Finding triage: codecleared_list_ignored_findings (finding:read or finding:write), codecleared_ignore_finding / codecleared_unignore_finding (finding:write). Prefer scope=occurrence; scope=rule or scope=cve is broader and survives rescan — use deliberately.
  • License governance: codecleared_list_license_allowances, codecleared_create_license_allowance, codecleared_delete_license_allowance, codecleared_list_license_overrides, codecleared_create_license_override, codecleared_delete_license_override, codecleared_append_license_policy_licenses (policy:read / policy:write / policy:admin — not in scan:all). Saving allowances does not start a scan.
  • Package review: codecleared_search_packages, codecleared_evaluate_package
  • Policy bundles (Quality Gates and more): codecleared_list_policy_bundle_schemas, codecleared_export_policy_bundle, codecleared_validate_policy_bundle, codecleared_import_policy_bundle — schemas default to codecleared.io/policy/1.1.0 (supports Quality Gate expressions)
  • Support tickets: codecleared_list_support_tickets, codecleared_get_support_ticket, codecleared_reply_support_ticket, codecleared_update_support_ticket_status

Example asks for an LLM

  • “Evaluate package express on npm for our organization.” → codecleared_evaluate_package
  • “Export our quality gates policy bundle.” → codecleared_export_policy_bundle with kind=quality
  • “Validate this quality bundle, then dry-run import.” → codecleared_validate_policy_bundle then codecleared_import_policy_bundle with dryRun=true
  • “Forbid packages with any known OSV vulnerabilities.” → export quality bundle, set a rule conditions.maxVulns: 0, validate, import

Common outcomes

A 402 means the requested scan type lacks eligible credits/entitlement, or the org has no MAU license for the token owner this month (seat_license_required). If a repository appears missing, verify the token’s organization and repository access rather than trying another organization’s token. codecleared_wait_for_scan can time out while the scan continues; retain the scan ID and ask for status later instead of starting a duplicate scan.

When a scan finishes with status: failed, inspect each projectUnits[].errorCode (and error message). Codes such as pat_required, lockfile_not_found, insufficient_credits, workflow_timeout, and system_error are stable. See Scan failures.

Related documentation