@id3-clarity/mcp-server
v1.23.0
Published
CLARITY Test Management — MCP server for Claude Desktop / Cursor / Cline / Windsurf
Maintainers
Readme
@id3-clarity/mcp-server
CLARITY Test Management — Model Context Protocol server. Connect Claude Desktop, Cursor, Cline, or Windsurf to your CLARITY instance and manage test cases, suites, runs, and projects entirely through natural language.
Overview
@id3-clarity/mcp-server exposes 164 tools from the CLARITY REST API as an MCP (Model Context Protocol) server. Once connected, your AI client can:
- Create and update test cases, folders, suites, runs, requirements, and releases without leaving your editor
- Search and inspect existing tests, execution history, and failure patterns
- Import test cases from JSON or from AI-generated suggestions
- Track run progress and mark individual executions as pass/fail/blocked/skipped
- Sync requirements with Jira bidirectionally (push, link, pull-sync, conflict detection)
- Manage releases with readiness scoring, requirement scope, and test run links
- Schedule recurring runs, attach evidence, comment with @-mentions, and read dashboard metrics
- Safely delete resources with a 2-step confirmation + 30-day Trash recovery
All operations are tenant-isolated, fully audit-logged, and rate-limited on the CLARITY backend. The server itself is a lightweight stdio process — no extra ports, no background daemons.
Quick Start (2 minutes)
1. Get your API token
In CLARITY, go to: Settings → API Access → MCP Tokens → + New Token
- Name: e.g.
Claude Desktop - <your name> - Scopes:
read+write(adddeleteonly if needed) - Projects: select the projects you'll work on (leave blank for org-wide access)
- Click Create, copy the
clr_...token — it is shown only once
2. Add to your AI client
Pick your client and paste the configuration. Replace only the clr_... token; all other values are pre-filled.
Claude Desktop
Config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Test environment (clarity-test.id3.com.tr):
{
"mcpServers": {
"clarity": {
"command": "npx",
"args": ["-y", "@id3-clarity/mcp-server@latest"],
"env": {
"CLARITY_API_URL": "https://clarity-test-api.id3.com.tr",
"CLARITY_API_TOKEN": "clr_PASTE_YOUR_TOKEN_HERE",
"CLARITY_LANG": "tr"
}
}
}
}Production (clarity.id3.com.tr):
{
"mcpServers": {
"clarity": {
"command": "npx",
"args": ["-y", "@id3-clarity/mcp-server@latest"],
"env": {
"CLARITY_API_URL": "https://clarity-api.id3.com.tr",
"CLARITY_API_TOKEN": "clr_PASTE_YOUR_TOKEN_HERE",
"CLARITY_LANG": "tr"
}
}
}
}Cursor
Config file: ~/.cursor/mcp.json — same JSON structure as Claude Desktop above.
{
"mcpServers": {
"clarity": {
"command": "npx",
"args": ["-y", "@id3-clarity/mcp-server@latest"],
"env": {
"CLARITY_API_URL": "https://clarity-api.id3.com.tr",
"CLARITY_API_TOKEN": "clr_PASTE_YOUR_TOKEN_HERE",
"CLARITY_LANG": "en"
}
}
}
}Cline (VSCode)
VSCode → Cline extension → Settings → MCP Servers → "Edit in JSON" → paste the same config as above.
Windsurf
Config file: ~/.windsurf/mcp.json — same structure.
3. Restart your AI client
Quit and reopen Claude Desktop / Cursor / Cline / Windsurf. The status bar will show "clarity (20 tools)" — that is correct, and not all of them.
Why 19 and not 164
An LLM's ability to pick the right tool degrades as the catalogue grows: around 78% accuracy at ten tools, collapsing past a hundred. Every extra tool makes the others harder to choose. So the server advertises a read-only core plus whichever domains you switch on, and nothing was merged or removed to get there — the full catalogue is one setting away.
Ask the assistant "what can CLARITY do?" and it will call list_capabilities, which lists every
domain and what it covers. To turn one on for the session it calls enable_domain. To make it
permanent, add CLARITY_MCP_DOMAINS:
"env": {
"CLARITY_API_URL": "https://clarity-api.id3.com.tr",
"CLARITY_API_TOKEN": "clr_...",
"CLARITY_MCP_DOMAINS": "testcases,runs,requirements"
}| Domain | What it covers |
|---|---|
| testcases | Writing test cases, suites, folders; comments, attachments, bulk operations |
| runs | Creating runs and writing results, scheduled runs, flaky tests, the discovery agent |
| defects | Reporting defects, triage, the retest queue and verification, defect KPIs |
| requirements | Writing requirements, linking test cases, traceability, Jira/Azure mapping |
| releases | Creating releases, managing scope, readiness |
| delivery | Code changes, pull request review, security scans, gates and approvals |
| insights | Dashboards, analytics, executive summary, environment matrix |
| workspace | Projects, folders, custom fields, users, tags |
| platform | Pipelines, webhooks, quota, schema discovery |
CLARITY_MCP_DOMAINS=all advertises everything, which is what installations did before this
existed. It is supported and it will make the assistant worse at choosing.
Write tools are off by default
The core is read-only: every tool that writes (create_requirement, create_test_case,
create_run …) sits in a domain and is not advertised until that domain is on. A domain is
visibility, not permission — every call is still bounded by the token's scopes, projects and the
user's role, so enabling requirements with a read-only token still answers INSUFFICIENT_SCOPE.
enable_domain is not enough in every client. It switches the domain on for the session and
sends notifications/tools/list_changed (the server declares tools.listChanged). Clients that
honour the notification (Claude Code) show the new tools at once; Claude Desktop was observed not
to re-read its tool list (CLAR-395), so the schema never loads. The durable fix is
CLARITY_MCP_DOMAINS in the config plus a client restart (or a new chat). enable_domain's
answer reports toolListChangedSent and the permanentSetting to use; calling a tool whose
domain is off returns DOMAIN_DISABLED with the domain and that fix.
Which domain opens which tools (generated from src/tools/domains.ts; domains.test.ts fails if
this table drifts — list_capabilities returns the same lists at runtime):
| Domain | Tools it opens (beyond the core) |
|---|---|
| testcases | add_test_case_attachment, add_test_case_comment, bulk_add_test_case_attachments, bulk_add_test_case_comments, bulk_create_suites, bulk_create_test_cases, bulk_move_test_cases, bulk_update_test_cases, create_suite, create_test_case, delete_suite, delete_test_case, generate_tests_from_document, generate_tests_from_requirement, get_suite, import_test_cases_json, list_suites, list_test_case_comments, update_suite, update_test_case |
| runs | analyze_failure_root_cause, bulk_update_execution_results, create_run, create_scheduled_run, get_discovery_run, get_failing_cases, get_flaky_tests, get_run_triage, get_test_execution_history, list_discovery_findings, list_scheduled_runs, pause_scheduled_run, run_backfill, run_transition, start_discovery_run, update_execution_result |
| defects | create_defect, get_defect, get_defect_kpis, get_defect_retest_queue, list_defects, push_defect_to_jira, record_defect_verification, set_defect_commitment, transition_defect |
| requirements | add_requirement_to_release, bulk_add_requirements_to_release, bulk_create_requirements, bulk_remove_requirements_from_release, create_requirement, delete_requirement, get_requirement_traceability, import_requirements_from_jira, link_requirement_to_jira, link_requirement_to_test_case, link_requirement_to_test_runs, link_requirements, link_test_run_to_covered_requirements, list_requirement_link_types, list_requirement_statuses, list_requirement_types, push_requirement_to_jira, push_requirement_update_to_jira, remove_requirement_from_release, sync_requirement, transition_requirement_in_jira, unlink_requirement_from_test_case, unlink_requirement_from_test_runs, unlink_requirements, update_requirement |
| releases | add_release_exit_criterion, add_release_gate, add_test_run_to_release, answer_release_exit_criterion, apply_release_exit_criteria_template, approve_release_gate, bulk_create_releases, create_release, create_release_scope_baseline, delete_release, evaluate_release_gates, generate_release_notes, get_release_platform_readiness, get_release_readiness, list_release_sign_offs, record_decision, record_release_sign_off, remove_test_run_from_release, update_release |
| delivery | act_on_pull_request, attach_scan, auto_match_code_changes, delete_code_area, deploy_precheck, env_release, env_reserve, evaluate_quality_gate, gate_publish, generate_tests_for_change, get_approval_status, get_code_change, get_code_change_diff, get_code_change_review, get_ingest_status, get_requirement_code_changes, get_scan_debt, link_code_change_to_requirement, list_branches, list_code_areas, list_pull_requests, list_scan_jobs, list_scan_profiles, propose_merge, request_approval, request_scan, resolve_finding, review_code_change, review_requirement_implementation, suggest_code_areas, sync_requirement_code_changes, upsert_code_area |
| insights | get_environment_matrix, get_executive_narrative, get_project_analytics, rank_tests_by_failure_risk |
| workspace | create_custom_field, create_folder, create_folder_tree, create_project, delete_folder, get_folder_tree, get_project_stats, get_user, list_custom_fields, list_folders, list_tags, list_users, update_folder, update_project |
| platform | ci_trigger, clarity_propose, get_my_quota, get_schema, get_test_type_info, list_ci_run_definitions, list_pipelines, list_webhooks |
4. Test the connection
Try: "List my CLARITY projects"
The AI calls list_projects and returns your accessible projects with IDs you can use in follow-up prompts.
Keeping up to date
The configs above pin @latest, so each cold start pulls the newest published
version — restarting your AI client is usually enough to update.
If you installed globally (npm i -g @id3-clarity/mcp-server), update manually:
npm i -g @id3-clarity/mcp-server@latest
npm ls -g @id3-clarity/mcp-server # verify the versionThe CLARITY backend also tells you when you're behind: every response to an outdated
client starts with a clientUpdate block (your version, the current one, and the exact
steps — restart for npx …@latest, npm i -g for a global install), shown as a separate
"⚠️" message from 1.19.0 on, and an old version's failures say they may be caused by the
version. Unsupported versions are refused with the same steps. So if the AI mentions an
update, follow it before reporting a problem.
Which version am I running?
- Ask the AI: "Which CLARITY MCP version is running?" — from 1.20.0 it calls
list_capabilities, whose first field (server) gives the running version, the latest release, whether you are current, and the update steps if not. - CLARITY → Settings → MCP Tokens: each token shows the version it last called from and whether it is current.
- Terminal (global install):
clarity-mcp-server --version. - Client log: the startup line reads
@id3-clarity/mcp-server <version> ready(Claude Desktop:mcp-server-clarity.log).
Prerequisites
- Node.js 18+ (used by
npxto fetch and run the server) - A CLARITY API token — create one at CLARITY → Settings → API Access → MCP Tokens → New Token
Tokens look like clr_<32 alphanumeric characters>.
Installation
The recommended way is npx (no global install needed). The snippet in the Quick Start section is all you need.
If you prefer a global install:
npm install -g @id3-clarity/mcp-serverThen replace "command": "npx", "args": ["-y", "@id3-clarity/mcp-server@latest"] with "command": "clarity-mcp-server" in your config.
Authentication
Creating a token
- Log in to CLARITY and open Settings → API Access → MCP Tokens
- Click + New Token
- Fill in:
- Name — a human-readable label (e.g.
Cursor - kaan) - Scopes —
read,write, and/ordelete(grant only what you need) - Project access — specific projects, or leave blank for all accessible projects
- Expiry — optional; recommended for shared/CI tokens
- Name — a human-readable label (e.g.
- Click Create and copy the token immediately — it will not be shown again
Token format
clr_<32 alphanumeric characters>Rotating a token
Go to Settings → API Access → MCP Tokens, find the token, click Revoke, and create a new one. Update the CLARITY_API_TOKEN env var in your AI client config and restart.
Minimum required scopes
| Task | Required scopes |
|------|----------------|
| Read projects, folders, test cases, runs | read |
| Create / update test cases, suites, runs | read + write |
| Delete test cases / folders / suites | read + write + delete |
| Admin operations | admin |
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| CLARITY_API_URL | Yes | — | API base URL, e.g. https://clarity-api.id3.com.tr |
| CLARITY_API_TOKEN | Yes | — | Token in clr_<32 alphanumeric> format |
| CLARITY_LANG | No | en | tr or en — switches tool description language shown to the AI |
| CLARITY_MCP_DOMAINS | No | (core only) | Comma-separated capability domains to advertise, e.g. requirements,runs; all for everything. Write tools are off until their domain is listed. See Write tools are off by default |
Available Tools (164)
Generated from
src/tools/index.ts(v1.11.2). Scopes follow the pattern: read tools needread, mutating tools needwrite, destructive tools needdelete.
Projects (5)
| Tool | Description | Required scope |
|---|---|---|
| list_projects | Lists CLARITY projects accessible to your token | read |
| get_project | Returns details of a specific project | read |
| get_project_stats | Project statistics (case count, last 30 days success rate) | read |
| create_project | Creates a new project | write |
| update_project | Updates project info | write |
Folders (4)
| Tool | Description | Required scope |
|---|---|---|
| list_folders | Lists folders in a project (flat) | read |
| get_folder_tree | Returns folder hierarchy as a tree | read |
| create_folder | Creates a folder; use parentId for nested | write |
| update_folder | Updates folder name/parent | write |
Test Cases (7)
| Tool | Description | Required scope |
|---|---|---|
| list_test_cases | Lists test cases (paginated) with folderId/type/priority/status/tag/search filters | read |
| get_test_case | Returns test case detail (steps + metadata + relations) | read |
| search_test_cases | Full-text search by title in test cases | read |
| create_test_case | Creates a test case; non-MANUAL/AUTOMATED types auto-coerce to MANUAL + testTypes | write |
| update_test_case | Updates test case fields | write |
| bulk_create_test_cases | Bulk create test cases (max 50); for more use import_test_cases_json | write |
| import_test_cases_json | Bulk import via CLARITY JSON schema; folderPath found or created, duplicateStrategy | write |
Suites (4)
| Tool | Description | Required scope |
|---|---|---|
| list_suites | Lists test suites | read |
| get_suite | Returns suite detail with included cases | read |
| create_suite | Creates a new test suite | write |
| update_suite | Updates a suite; addCaseIds/removeCaseIds for case management | write |
Runs (5)
| Tool | Description | Required scope |
|---|---|---|
| list_runs | Lists test runs; supports status filter | read |
| get_run | Returns run metadata only — not execution results (use get_run_progress for counts, get_failing_cases with runId for names) | read |
| get_run_progress | Run progress statistics (pass/fail/skip/blocked/pending counts) | read |
| create_run | Creates a test run; either testSuiteId OR testCaseIds[] required | write |
| update_execution_result | Updates execution result for a case within a run (PASS/FAIL/SKIP/BLOCKED) | write |
Requirements (12)
| Tool | Description | Required scope |
|---|---|---|
| list_requirements | Lists requirements with type/status/priority/assignee/source/syncStatus/testable/search filters | read |
| get_requirement | Returns full requirement detail incl. attachments and Jira/Azure sync status; for a Jira-linked requirement also its live Jira issue links (jiraLinks, null + reason if Jira is unreachable) | read |
| create_requirement | Creates a requirement; accepts legacy type/status keys or typeId/statusId UUIDs | write |
| update_requirement | Updates requirement fields; linked items auto-flip syncStatus to pending | write |
| link_requirement_to_test_case | Links a requirement to up to 100 test cases per call (idempotent) | write |
| link_requirement_to_test_runs | Links a requirement to up to 100 existing test runs of its project per call (idempotent) | write |
| link_test_run_to_covered_requirements | Links a run to every requirement in its project whose covering test cases it executed (idempotent) | write |
| unlink_requirement_from_test_case | Removes a requirement ↔ test case link (idempotent no-op if absent) | write |
| unlink_requirement_from_test_runs | Removes up to 100 requirement ↔ test run links per call; reports removed / notLinked (idempotent) | write |
| get_requirement_traceability | Requirement → test case → last execution traceability matrix with coverage % | read |
| list_requirement_types | Lists requirement types (system defaults + project overrides) | read |
| list_requirement_statuses | Lists requirement statuses (system defaults + project overrides) | read |
Jira Sync (7)
| Tool | Description | Required scope |
|---|---|---|
| push_requirement_to_jira | Pushes a manually-created requirement to Jira as a new issue | write |
| link_requirement_to_jira | Links a requirement to an existing Jira issue (fields overwritten from Jira) | write |
| sync_requirement | One-way pull-sync from Jira/Azure DevOps to local; reports conflicts | write |
| push_requirement_update_to_jira | Pushes CLARITY changes up to the linked Jira issue (last-write-wins + conflict detection) | write |
| list_requirement_link_types | Jira issue link types of the project's Jira with their outward / inward phrases (CLAR-314) | read |
| link_requirements | Creates Jira issue links between requirements' issues (or to a raw key in the bound Jira project); single pair or up to 25 under one confirmation; all pairs validated before any write; existing links answered already_exists; verified by reading Jira back | write |
| unlink_requirements | Deletes one Jira issue link from a requirement's issue; always its own confirmation | write |
Releases (21)
| Tool | Description | Required scope |
|---|---|---|
| list_releases | Lists releases; auto-computed coveragePercent / overallPassRate / readinessScore | read |
| get_release | Release detail — merged test runs (direct + inherited via requirements) | read |
| create_release | Creates a release; optional Jira fixVersion/sprint scope binding | write |
| update_release | Partial update; status="released" auto-sets actualDate | write |
| add_requirement_to_release | Links a requirement to a release; related runs auto-inherited | write |
| remove_requirement_from_release | Unlinks a requirement from a release (idempotent) | write |
| bulk_remove_requirements_from_release | Bulk-unlink up to 500 requirements from a release | write |
| add_test_run_to_release | Directly attaches a test run with a runType classification | write |
| remove_test_run_from_release | Detaches a directly attached test run; an inherited-only run is reported with its requirement(s) and a pointer to unlink_requirement_from_test_runs (idempotent) | write |
| get_release_readiness | Readiness score (40% pass rate + 25% coverage + 20% execution progress + 15% gates), gates and blockers; muted failures are discounted but cap the release below READY | read |
| get_release_platform_readiness | Readiness per platform (Web, iOS, Android, Smart TV, Set-Top Box, Apple TV …): runs, executed/total, pass rate, failed/blocked, requirement coverage, last run and status per platform, plus the verdict over the release's required platforms (CLAR-368) | read |
| apply_release_exit_criteria_template | Seeds exit criteria from the template of the release's own type; additive (existing keys skipped) | write |
| add_release_exit_criterion | Adds one derived (metric/operator/threshold) or manual exit criterion | write |
| answer_release_exit_criterion | Answers a manual criterion met / not_met; null withdraws the answer | write |
| add_release_gate | Adds an auto (with condition) or manual quality gate; the token owner is the requester | write |
| evaluate_release_gates | Re-evaluates auto gates against current metrics; needs release:execute | write |
| approve_release_gate | Approves a manual gate; self-approval needs a reason (four-eyes); needs release:execute | write |
| record_release_sign_off | Records go / conditional_go / no_go, append-only, evidence sealed; needs release:execute | write |
| list_release_sign_offs | Every recorded go/no-go, newest first, with seal and scope-drift status | read |
| record_decision | Writes to the project's decision log (rationale required, append-only) | write |
| generate_release_notes | Markdown release-notes draft; save: true stores it on the release | write |
| create_release_scope_baseline | Freezes the release's current requirement scope as a baseline (drift is measured against it) | write |
Defects (8)
| Tool | Description | Required scope |
|---|---|---|
| list_defects | Lists defects, filterable by release, status, severity and openOnly | read |
| get_defect | One defect with its links, full status history and allowedTransitions | read |
| get_defect_retest_queue | Claimed fixes nobody has re-tested (verificationState=awaiting) | read |
| get_defect_kpis | Open / escaped / awaiting-retest / unclassified counts, each with its own state | read |
| create_defect | Reports a defect (always born new); detectedPhase required | write |
| transition_defect | Moves a defect through the state machine — the only door to status. On a CLARITY defect linked to Jira (status push on) it also transitions the Jira issue, and prompts for confirmation first (CLAR-391) | write |
| record_defect_verification | Writes a retest result; needs defect:execute | write |
| set_defect_commitment | Release-commitment decision: targeted (needs a release), under_review, not_planned (needs a reason) | write |
| push_defect_to_jira | Creates the Jira issue (Bug by default) for a CLARITY defect, links it and attaches execution evidence; status, priority and comments then sync both ways. Prompts for confirmation (CLAR-366) | write |
Three things an agent must not get wrong here.
openOnlyis not "not closed" — an unclassified (unmapped) defect is neither, andget_defect_kpisis where you find out how many there are. A KPI withstate: "unknown"is NOT zero: it means the measurement did not happen, and reporting it as "0 open defects" turns "hold this release" into "ship it". Andrecord_defect_verificationdoes not close anything — it writes the evidence that MAKESresolved → closedlegal for afixedresolution; the close is a separatetransition_defectcall.
Users (2)
| Tool | Description | Required scope |
|---|---|---|
| list_users | Lists users assigned to a project (id, email, name, role) | read |
| get_user | Returns user details — role, department, last login, membership count | read |
Tags (1)
| Tool | Description | Required scope |
|---|---|---|
| list_tags | Lists all unique tags used in a project's test cases, alphabetically | read |
Custom Fields (1)
| Tool | Description | Required scope |
|---|---|---|
| list_custom_fields | Lists tenant-scoped custom field definitions | read |
Webhooks (1)
| Tool | Description | Required scope |
|---|---|---|
| list_webhooks | Lists webhooks scoped to the project or tenant-wide | read |
Pipelines (1)
| Tool | Description | Required scope |
|---|---|---|
| list_pipelines | Lists CI/CD pipelines with their most recent run status | read |
Dashboard (1)
| Tool | Description | Required scope |
|---|---|---|
| get_dashboard_metrics | Analytics digest (cases, runs, pass rate, recent failures, flaky, avg execution time) | read |
Attachments (1)
| Tool | Description | Required scope |
|---|---|---|
| add_test_case_attachment | Attaches external evidence to a test case via URL (no file upload) | write |
Comments (1)
| Tool | Description | Required scope |
|---|---|---|
| add_test_case_comment | Adds a markdown comment; mentions[] triggers @-mention notifications | write |
Scheduled Runs (3)
| Tool | Description | Required scope |
|---|---|---|
| list_scheduled_runs | Lists scheduled test runs; status filter (active/paused/completed/failed) | read |
| create_scheduled_run | Creates a scheduled run for a suite (cron or interval schedule) | write |
| pause_scheduled_run | Pauses an active scheduled run (status=paused) | write |
Reports & Insights (2)
| Tool | Description | Required scope |
|---|---|---|
| get_failing_cases | Top failing test cases in the last N days; with runId, that run's failed/blocked executions with an explicit truncated flag | read |
| get_test_type_info | Test type enum values and descriptions (MANUAL/API/AUTOMATED etc.) | read |
AI generation, root cause, risk and triage (5) — since 1.22.0
What CLARITY's own AI and ML do, for an agent. The two generation tools and the root-cause tool send text to the organization's AI provider and spend its AI quota, so both of their modes ask for confirmation (C2). Ranking and triage are reads.
| Tool | Description | Required scope |
|---|---|---|
| generate_tests_from_requirement | Proposes test cases for a requirement (requirementId, or requirementText ≤ 20,000 chars). With accept (≤ 12 proposals, named one by one) saves them, linked to the requirement. Without accept nothing is written. Domain testcases | write |
| generate_tests_from_document | Same, from a document: source: {text ≤ 60,000, title?} or {url, kind: openapi \| documentation} (read server-side, public addresses only). Only the first 4000 characters reach the model — basis.truncated says when it was cut. Domain testcases | write |
| analyze_failure_root_cause | AI root cause of one failed execution (executionId; the test case is derived from it). generatedBy is ai, or the keyword stand-in with fallbackReason. Domain runs | write |
| rank_tests_by_failure_risk | Ranks testCaseIds / a suiteId / a runId by chance to fail on the next run. source: ml_model (project model passed its gate) or heuristic; modelAvailable: false with an empty list when the prediction service is down — never zeros. Domain insights | read |
| get_run_triage | A finished run's automatic triage: summary, per failure category, source (rule / ai / rules_fallback), status, linked defect. summary: null = not triaged yet. Domain runs | read |
Suggest → accept: call once without accept, confirm, read suggestions, then call again with
accept: [the ones to keep] and confirm. Suggestions derived from a Jira/Azure requirement, a
fetched document or a failure's output come back inside <untrusted> blocks; after reading
those, a session's outward writes (these C2 tools included) go through clarity_propose, where a
person approves them in CLARITY.
get_impacted_tests also takes rankBy: "risk" (default "evidence") to list the impacted
cases most likely to fail first; the order is applied before paging.
Discovery agent (3) — since 1.23.0
The discovery agent explores a project's configured environment read-only and proposes defect candidates (rule-based, accessibility, AI) and untested screens. An agent can start one and read the results; accepting or dismissing a finding stays a human decision in the CLARITY UI.
| Tool | Description | Required scope |
|---|---|---|
| list_discovery_findings | Findings of a project (open by default), filterable by status, kind, category, runId. Page-derived text comes back inside <untrusted> blocks | read |
| get_discovery_run | One discovery (latest when runId is omitted): status, progress against the caps, stop reason, counters, the exploratory test run it was recorded as | read |
| start_discovery_run | Queues a discovery of the configured environment; needs pipeline:execute, refused when off on the server or project, while another runs, or after 5 in 24 hours | write |
Meta (2)
| Tool | Description | Required scope |
|---|---|---|
| get_my_quota | Shows your token's scopes, accessible projects, and rate limits | read |
| get_schema | Returns list of all tools or schema of a specific tool | read |
Code Changes & the Change Gate (7)
Reading what was actually built, and whether it is safe to merge.
| Tool | Description | Required scope |
|---|---|---|
| list_code_changes | Commits and pull requests ingested for a project. statsMeasured: false = file/line counts unknown (null), not zero; includeFiles adds the changed paths (first 50) | read |
| get_code_change | One change with its risk factors and linked tests | read |
| get_code_change_files | The files a change touched | read |
| get_code_change_diff | The unified diff, read live from the provider | read |
| get_code_change_review | Approval state and reviewers, normalised across providers | read |
| get_change_gate | The merge verdict and the evidence behind it | read |
| attach_scan | Attaches a SARIF security scan and classifies it against the baseline | write |
Change impact & code areas (6)
"These changes landed — what do I re-test, and where are tests missing?" get_change_impact and
get_impacted_tests are in the always-visible core; the four area tools are in delivery.
| Tool | Description | Required scope |
|---|---|---|
| get_change_impact | For 1–50 changes (codeChangeIds) or a since/until/branch window of a project: code areas touched (with files), existing test cases to re-test (why: file / requirement / area, 0–100 confidence), areasWithoutTests, unmatchedFiles, changesWithoutStats, a ready suggestedRun and nextSteps. Measures up to 20 unmeasured changes first | read |
| get_impacted_tests | The same for one change (codeChangeId), per-channel availability in byFile / byRequirement / byArea | read |
| list_code_areas | The project's code areas: path globs → test-case folders and tags, with testCaseCount and recentChangeCount | read |
| suggest_code_areas | Proposes areas from where recent changes cluster, with name-similar folders/tags. Saves nothing | read |
| upsert_code_area | Creates an area (name + pathPatterns) or updates one by areaId | write |
| delete_code_area | Soft-deletes an area (2-step confirmation); tests, folders and tags are untouched | write |
Recommended workflow:
get_change_impact { projectId, since: "<last release date>", branch: "develop" }(or passcodeChangeIds).- Re-test the listed cases —
suggestedRunalready holdscreate_run's arguments (runsdomain). Highest confidence first. - For
areasWithoutTests, callgenerate_tests_for_change(asks for confirmation; spends AI quota) and accept the useful proposals. - If
unmatchedFilesis large, orbyArea.reasonisNO_CODE_AREAS, callsuggest_code_areas, review with the user, and save withupsert_code_area. The next impact call maps those files to areas.
changesWithoutStats lists changes whose file list is still unknown — their impact is
unknown, not empty. tests.state: "unknown" likewise never means "nothing is impacted".
SCM (4)
Live reads against GitHub, Bitbucket, Azure DevOps and GitLab.
| Tool | Description | Required scope |
|---|---|---|
| list_branches | Branches across a project's repositories | read |
| list_pull_requests | Pull requests, optionally filtered by state | read |
| get_ingest_status | Why changes are — or are not — arriving on their own | read |
| run_backfill | Imports the history that predates the webhook (safe to re-run) | write |
These tools distinguish "could not look" from "nothing found." Every one of them reads a third-party system over a credential that can expire or lose a scope, so failures are reported next to the data rather than instead of it:
failedRepositories,skipped[].reason,available: false. An empty list from a repository CLARITY could not read is not evidence that nothing is happening — and an agent that reports it as such has been misled by a 401.
Scan Orchestration (4)
| Tool | Description | Required scope |
|---|---|---|
| list_scan_profiles | The scan profiles a project can run | read |
| request_scan | Create a scan job and try to run it | write |
| list_scan_jobs | Scan jobs and what became of them | read |
| get_scan_debt | Outstanding findings from earlier scans, and what has been paid down | read |
blockedReasonis the field that matters onrequest_scan. A job with no CI connection and no runner is queued, not running. An agent that reports it as "scan started" has told its user something untrue that nothing will correct later. Likewisequeued,failedandexpiredonlist_scan_jobsall mean no result arrived — andget_scan_debtreportsneverScannedrather than zero, because zero debt and a clean project look identical and are opposites.
Delete (5)
| Tool | Description | Required scope |
|---|---|---|
| delete_test_case | Soft-deletes a test case (restorable for 30 days), 2-step confirmation | delete |
| delete_folder | Soft-deletes a folder + cases inside, 2-step confirmation | delete |
| delete_suite | Deletes a suite (cases remain), 2-step confirmation | delete |
| delete_requirement | Soft-deletes a requirement (test case links removed), 2-step confirmation | delete |
| delete_release | Soft-deletes a release (linked runs/requirements intact), 2-step confirmation | delete |
Delete tools (
delete_test_case,delete_folder,delete_suite,delete_requirement,delete_release) require a 2-step confirmation flow: the first call returnsrequiresConfirmation: truewith aconfirmationTokenand a preview of what will be deleted; the second call passes the token to confirm. The confirmation window expires after 60 seconds.
Examples
Here are prompts you can paste directly into your AI client. The AI picks the correct tool(s) automatically.
1. List your projects
Show me my CLARITY projects.Calls list_projects.
2. Generate test cases from a requirement
Read this requirement and create 10 test cases in the "Auth/Login" folder of project "E-commerce":
> Users must log in with email and password. Rate-limited to 5 attempts per minute.
> Lockout after 10 failed attempts. Password minimum 8 characters.Calls import_test_cases_json with duplicateStrategy: "skip" (the folder path in the JSON is found or created).
3. Find failing tests
Which test cases failed most often this month in project "E-commerce"?Calls get_failing_cases({ projectId, days: 30, limit: 10 }).
4. Check run progress
How is the "Sprint-42 Smoke" run going?Calls list_runs to resolve the run ID, then get_run_progress.
5. Mark an execution as failed
Mark the case "User can checkout with VISA" in the "Sprint-42 Smoke" run as FAIL
with comment: "payment-service returned 502 — see incident #4521"Calls search_test_cases + list_runs to resolve IDs, then update_execution_result.
6. Bulk-create test cases
Create 5 test cases for the password-reset flow in the "Auth" folder of project "E-commerce".
Cover: request email, invalid email, expired link, successful reset, and password reuse rule.Calls bulk_create_test_cases with up to 50 cases in a single request.
7. Safe folder deletion
Delete the "legacy-api" folder from project "E-commerce".First call returns a preview and a confirmationToken. The AI shows you the preview and asks for confirmation before proceeding with the second call.
Troubleshooting
"Connected to clarity (0 tools)" or no tools listed
- Check
CLARITY_API_URL— must include the scheme and no trailing slash (e.g.https://clarity-api.id3.com.tr) - Verify
CLARITY_API_TOKENstarts withclr_ - Restart the AI client after editing the config file
A new version was published but the old one keeps running
npx runs a command of that name already on PATH before it consults the
registry, so a global install silently pins you to an old version with no error:
which clarity-mcp-server # a path means a global install exists
npm ls -g --depth=0 | grep clarity # shows which version
npm uninstall -g @id3-clarity/mcp-servernpm view @id3-clarity/mcp-server version is the authority on what is current;
the npmjs.com package page is cached and can lag behind a publish.
create_requirement (or another write tool) cannot be called
Its domain is off — write tools are not advertised by default. Add the domain to the config, comma-separated with any others, and restart the client (or open a new chat):
"CLARITY_MCP_DOMAINS": "requirements,runs"In the SAME chat the model can call enable_domain({ domain }); clients that honour
notifications/tools/list_changed (e.g. Claude Code) then show the domain's tools, and a write
tool is called directly. Clients that ignore the notification (observed in Claude Desktop) need
the setting above and a restart for write tools: call_tool({ name, arguments }) carries
read-only tools only and refuses one that changes data (CALL_TOOL_READ_ONLY), because
through it the client could not show the user which change is about to happen or ask first.
If a write tool answers INSUFFICIENT_SCOPE, the token lacks the write scope.
INVALID_TOKEN
The token has been revoked or never existed. Create a new one at CLARITY → Settings → API Access → MCP Tokens → New Token.
INSUFFICIENT_SCOPE
The token lacks the scope the tool needs. Edit the token at Settings → API Access → MCP Tokens and enable the required scope (read, write, or delete).
PROJECT_NOT_ACCESSIBLE
The token is scoped to specific projects and the requested project is not in its allowlist. Either expand the token's project access or use a different token.
RATE_LIMIT_EXCEEDED
CLARITY enforces 60 requests/minute per token by default. Wait a few seconds and retry. For bulk operations, use bulk_create_test_cases instead of looping over create_test_case.
CONFIRMATION_EXPIRED
The 60-second confirmation window for a destructive operation expired. Retry the delete call to receive a fresh confirmationToken.
TENANT_CONTEXT_MISSING
The API token has no tenant association. This usually means the token was created before a tenant was configured. Create a new token after verifying your CLARITY workspace is fully set up.
The server starts but the AI can't find a project
Use list_projects first to confirm the project ID. Project names are case-sensitive in search filters; use projectId (UUID) in tool calls for reliability.
Privacy & Security
Tenant isolation
Every API call is executed under the tenant associated with your token. The server cannot access data from other tenants, even if you supply a cross-tenant ID. This isolation is enforced at the CLARITY backend, not only in the MCP layer.
Audit logging
Every tool call — including the initiating token ID, source IP, tool name, parameters, and result — is written to CLARITY's immutable audit log. Administrators can review this log at Settings → Audit Log.
Least-privilege tokens
Grant only the scopes your workflow actually needs:
- Read-only monitoring / dashboards →
readscope only - Content creation (AI-generated tests) →
read+write - Cleanup / migrations →
read+write+delete
IP allowlist
For production tokens, navigate to Settings → API Access → MCP Tokens → [token] → IP Allowlist and restrict the token to specific CIDR ranges.
Token soft-lock
If a token triggers more than 5 destructive operations within 60 seconds, it is automatically soft-locked for 1 hour as a safety net against runaway automation. An administrator can unlock it at Settings → API Access → MCP Tokens.
Treat tokens like passwords
- Never paste a token into a chat, issue, or screenshot
- Never commit tokens to source control
- Rotate tokens whenever a team member leaves or a device is compromised
- Use short-lived tokens (set an expiry) for CI pipelines
Key rotation procedure
- Create a new token at Settings → API Access → MCP Tokens → New Token
- Update
CLARITY_API_TOKENin your AI client config - Restart the AI client
- Revoke the old token at Settings → API Access → MCP Tokens → [old token] → Revoke
Development
git clone <repo>
cd packages/clarity-mcp-server
npm install
npm run buildLocal linking (test before publish)
npm link
# In your AI client config replace:
# "command": "npx", "args": ["-y", "@id3-clarity/mcp-server@latest"]
# with:
# "command": "clarity-mcp-server"Manual smoke test
CLARITY_API_URL=https://clarity-api.id3.com.tr \
CLARITY_API_TOKEN=clr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
CLARITY_LANG=en \
node dist/index.js
# Expect on stderr: "@id3-clarity/mcp-server ready (lang=en)"Running unit tests
npm testThe script collects files with find and passes them to node --test
individually. Two shorter forms do not work and both fail in ways that look
like something else:
node --test "dist-test/**/*.test.js"— the glob is quoted, so the shell does not expand it and Node has to. Node only learned to expand globs for--testin v21, and this package declaresengines: >=18. On Node 18 or 20 it printsCould not find '.../dist-test/**/*.test.js'— which reads like a missing build, not an unsupported flag. It passed locally on v22 and failed in CI.node --test dist-test/— Node treats the directory as one unit and executes its entry point, so the MCP server starts and dies withFatal: CLARITY_API_URL env var required. That looks like a missing environment variable in the test harness, and it is not.
The [ -n "$F" ] guard is not decoration: with no files, node --test falls
back to searching the working directory and hits the second failure above.
License
MIT — see LICENSE.
