# Clariti MCP server

Clariti is a cyber asset and exposure management platform for small and midsize businesses. Its MCP server lets an AI assistant read one Clariti workspace: its asset inventory, security findings, remediation steps and security posture history.

- Endpoint: `https://api.clariti-ai.xyz/mcp`
- Transport: MCP Streamable HTTP, stateless, JSON responses (every message is one `POST`)
- Auth: a Clariti API key with **Read only** access, sent on every request as `Authorization: Bearer clk_...`
- Access: read-only. There are no write tools, and every tool runs in a read-only database transaction limited to the key's workspace.

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `list_assets` | `asset_type` (DEVICE, USER, SOFTWARE, CLOUD, NETWORK, OTHER), `source`, `status` (ACTIVE, STALE, DECOMMISSIONED), `limit` (1-100, default 25), `cursor` | A page of asset summaries, newest first, plus `next_cursor`, `has_more`, `total`. One record per source: a laptop seen by two tools appears twice. |
| `get_asset` | `asset_id` | One asset in full: identity, OS, owner, IP and MAC addresses, security posture, installed software (first 100 plus `software_total`), the last 10 field changes and correlation edges to the same asset seen by other sources. |
| `list_findings` | `severity` (list of critical, high, medium, low, info), `status` (list of open, in_progress, resolved, accepted_risk, false_positive; default open and in_progress), `finding_type`, `asset_id`, `q` (text search), `limit`, `cursor` | A page of finding summaries, newest first, plus `next_cursor`, `has_more`, `total`. Each carries `exposure_category`, `exposure_points` and `projected_lift` (score points, 0-100, recovered once the fix is verified); all three are null when the finding does not count toward the exposure score. |
| `get_finding` | `finding_id` | One finding in full: description, severity, status, affected asset ids, owner, due date, KEV / EPSS / CVSS, remediation and console links. |
| `remediation_steps` | `finding_id` | How to fix one finding: `remediation_steps`, `verification_query`, vendor `console_url` and `docs_url`. `remediation_status` is `ready`, `pending` (still being written) or `unavailable`. |
| `posture_history` | `days` (1-365, default 30) | Daily posture snapshots, oldest first: `overall_score` and the EDR coverage, MFA adoption, encryption and patch currency dimensions, asset count and a confidence band. Also `score_model_version` (`1` is the coverage model, `2` and later the exposure model; `3` since 2026-10), `exposure_overall`, `categories` (`key`, `label`, `score` (null when not measured), `measured`, `weight`, `finding_count`, `accepted_count`, `sources`) and `ceiling` (a confirmed CISA KEV capping the score: `value`, `breadth`, `uncapped`, `binding`, `finding_ids`, `findings`), or null. |
| `nl_query` | `template` or `question`, optional `params` | Answers common questions from curated query templates: a one-line `answer` plus the `data` rows behind it. A `question` is matched to a template; one no template covers returns an error listing the templates, never an ad-hoc query. |

`overall_score` and the coverage figures are fractions from 0 to 1, not percentages. Exposure category scores, `exposure_overall` and `projected_lift` are 0-100. Never compare `overall_score` across days whose `score_model_version` differs: the models measure different things.

## nl_query templates

Asset counts (`asset_count`, `asset_count_by_type`, `asset_count_by_source`, `asset_count_by_status`), `stale_assets` (`days`), `asset_search` (`q`), `assets_missing_source` (`source`), finding counts (`open_findings_count`, `findings_by_severity`, `findings_by_type`), `recent_findings` (`days`), `findings_for_asset` (`asset_id`), `unassigned_findings`, `overdue_findings`, posture (`posture_score`, `posture_breakdown`, `posture_trend` (`days`), `posture_biggest_drop`), coverage (`edr_coverage`, `mfa_adoption`, `encryption_rate`, `devices_missing_edr`), data quality (`quality_score`, `worst_quality_assets`, `conflict_count`) and integrations (`adapter_status`, `failing_adapters`). The `nl_query` tool description lists them all with their parameters.

## Errors

- HTTP `401`: no key, or an invalid or revoked key.
- HTTP `403`: the key is not a Read only key (Export only and Read & write keys are refused), or the admin who created it is disabled.
- HTTP `429`: more than the workspace's per-minute request limit. Retry after the `Retry-After` seconds.
- Tool error (`isError: true`): bad arguments, or a record that does not exist in this workspace. The message says which.

More: https://docs.clariti-ai.xyz/mcp