@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 (v1.5.0) exposes 68 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 (add delete only 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"],
      "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"],
      "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"],
      "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 should show "clarity (68 tools)" or similar.

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.

Prerequisites

• Node.js 18+ (used by npx to 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-server

Then replace "command": "npx", "args": ["-y", "@id3-clarity/mcp-server"] with "command": "clarity-mcp-server" in your config.

Authentication

Creating a token

1. Log in to CLARITY and open Settings → API Access → MCP Tokens
2. Click + New Token
3. Fill in:
   • Name — a human-readable label (e.g. Cursor - kaan)
   • Scopes — read, write, and/or delete (grant only what you need)
   • Project access — specific projects, or leave blank for all accessible projects
   • Expiry — optional; recommended for shared/CI tokens
4. 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 |

Available Tools (68)

Generated from src/tools/index.ts (v1.5.0). Scopes follow the pattern: read tools need read, mutating tools need write, destructive tools need delete.

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 with folderStrategy / 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 detail with execution results | 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 (9)

| 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 | 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 | | unlink_requirement_from_test_case | Removes a requirement ↔ test case link (idempotent no-op if absent) | 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 (4)

| 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 |

Releases (9)

| 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 | | get_release_readiness | Readiness score (60% pass rate + 40% coverage), gates and blockers | read |

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 | read | | get_test_type_info | Test type enum values and descriptions (MANUAL/API/AUTOMATED etc.) | read |

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 |

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 returns requiresConfirmation: true with a confirmationToken and 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 folderStrategy: "find-or-create" and duplicateStrategy: "skip".

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_TOKEN starts with clr_
• Restart the AI client after editing the config file

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 → read scope 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

1. Create a new token at Settings → API Access → MCP Tokens → New Token
2. Update CLARITY_API_TOKEN in your AI client config
3. Restart the AI client
4. 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 build

Local linking (test before publish)

npm link
# In your AI client config replace:
#   "command": "npx", "args": ["-y", "@id3-clarity/mcp-server"]
# 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 test

License

MIT — see LICENSE.