> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useverdikt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP setup (Cursor)

> Connect Verdikt MCP tools in Cursor or Claude Code.

The Verdikt MCP server lets coding agents open cert windows, post signals, and read gate decisions without leaving the IDE.

## Prerequisites

* [API key](/agent/api-keys) (`vdk_live_…`) from **Settings → Agent access**
* Workspace ID from **Settings → General**
* Node.js 18+

## 1. Cursor config

Add to **`~/.cursor/mcp.json`** (global) or **`.cursor/mcp.json`** (project):

```json theme={"dark"}
{
  "mcpServers": {
    "verdikt": {
      "command": "npx",
      "args": ["-y", "@useverdikt/mcp@0.1.4"],
      "env": {
        "VERDIKT_API_URL": "https://api.useverdikt.com",
        "VERDIKT_API_KEY": "vdk_live_…",
        "VERDIKT_WORKSPACE_ID": "ws_…"
      }
    }
  }
}
```

Replace secrets with your values. For local API dev, set `VERDIKT_API_URL` to `http://127.0.0.1:8787`.

Restart Cursor after saving. First run downloads `@useverdikt/mcp` from npm — no clone or local path required.

<Note>
  **Settings → Agent access** includes a pre-filled copy of this config with your workspace ID.
</Note>

## 2. Optional agent rule

Copy the [agent rule](/agent/agent-rule) into your project (e.g. `.cursor/rules/verdikt.mdc` for Cursor, or `AGENTS.md` / `CLAUDE.md` for other agents) so the agent calls **`release_brief`** when the gate is blocked — not just **`check_gate`** in a loop.

## Tools available

| Tool                          | Purpose                                                                                                                           |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `create_release`              | Open cert window (pass `commit_sha`, `pr_number`, repo metadata)                                                                  |
| `post_signals`                | Submit signal values for a release                                                                                                |
| `get_verdict`                 | Read status, blocking signals, intelligence                                                                                       |
| `check_gate`                  | Merge decision — read **`action`**: `merge` \| `collecting` \| `self_heal` \| `recover_certification` \| `escalate`               |
| `check_gate_by_sha`           | Same gate lookup by PR commit SHA                                                                                                 |
| `release_brief`               | Deterministic brief when blocked — `top_blockers`, regression story, remediation debt, `gate_action`, `suggested_verb`, hub links |
| `get_regression_history`      | Regression streaks before escalate vs self-heal                                                                                   |
| `get_calibration_suggestions` | Pending prod threshold suggestions (human applies on Thresholds)                                                                  |
| `escalate`                    | Hand off to human when blocked                                                                                                    |
| `record_outcome`              | Post-deploy calibration                                                                                                           |

## Agent loop (read `action`, not exit code alone)

| `action`                | Behavior                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `merge`                 | Certified — merge/deploy allowed                                                   |
| `collecting`            | Signals in flight — poll **`check_gate`** during grace window only                 |
| `self_heal`             | Missing signals or post-grace collecting — fix and re-post                         |
| `recover_certification` | Remediation debt — ship clean CERTIFIED or corroborated `incident_hotfix`          |
| `escalate`              | Threshold failure — call **`release_brief`**, then **`escalate`** if still blocked |

When **`action` is not `merge`** and a human (or you) asks why the release is blocked, call **`release_brief(release_id)` once** instead of polling **`check_gate`** alone. Read **`gate_action`** for exact gate semantics and **`suggested_verb`** for coarse next steps (`merge` | `poll` | `escalate`).

Use **`mode: strict`** when only pure `CERTIFIED` (no override) should pass.

## Typical PR flow

1. Agent opens or updates a PR.
2. Apply label **`verdikt:rc`** (or `create_release` with commit SHA + repo metadata).
3. Integrations auto-pull; agent **`post_signals`** only for metrics CI produces locally.
4. **`check_gate`** or **`check_gate_by_sha`** — read **`action`**.
5. If not **`merge`**, **`release_brief`** for blockers and next steps — then fix, poll during collecting, or **`escalate`**.
6. GHA [gate workflow](/github/gate-workflow) + branch protection enforce merge even if the agent misbehaves.

## Session tracking

MCP sends `X-Verdikt-Agent-Session` on every request. Audit events for one agent run share the same session ID in the Verdikt audit trail. **`release_brief`** writes a distinct **`RELEASE_BRIEF_READ`** audit event (separate from **`RELEASE_GATE_CHECKED`**).

## Full MCP reference

Tool details, agent loop, and SHA tagging checklist: [@useverdikt/mcp on npm](https://www.npmjs.com/package/@useverdikt/mcp) (package README).