MCP setup (Cursor)

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

Prerequisites

API key (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):

{
  "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.

Settings → Agent access includes a pre-filled copy of this config with your workspace ID.

2. Optional agent rule

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

Agent opens or updates a PR.
Apply label verdikt:rc (or create_release with commit SHA + repo metadata).
Integrations auto-pull; agent post_signals only for metrics CI produces locally.
check_gate or check_gate_by_sha — read action.
If not merge, release_brief for blockers and next steps — then fix, poll during collecting, or escalate.
GHA 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 (package README).

Getting started

Connecting signals

GitHub integration

Agent setup

MCP setup (Cursor)

Prerequisites

1. Cursor config

2. Optional agent rule

Tools available

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

Typical PR flow

Session tracking

Full MCP reference

​Prerequisites

​1. Cursor config

​2. Optional agent rule

​Tools available

​Agent loop (read action, not exit code alone)

​Typical PR flow

​Session tracking

​Full MCP reference

Prerequisites

1. Cursor config

2. Optional agent rule

Tools available

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

Typical PR flow

Session tracking

Full MCP reference