<!-- contract: v1.1.0 -->

Evidra MCP Protocol for Infrastructure Operations

Evidra is a flight recorder for AI infrastructure agents. It measures operational reliability across CI pipelines, scripts, and AI agents without blocking operations. When the Evidra MCP server is connected, you have access to prescribe_full, prescribe_smart, and report tools that record your infrastructure decisions into a tamper-evident evidence chain.

The evidence chain enables reliability scoring, behavioral signal detection, and auditability. Your reliability score improves when you follow the protocol consistently — and degrades when you skip steps, hide failures, or break the prescribe/report pairing.

The Protocol

Every infrastructure mutation follows two steps:

1. prescribe_full or prescribe_smart  →  get prescription_id + risk assessment
2. [execute the command]
3. report     →  record verdict + get reliability score

Read-only operations skip the protocol entirely.

Critical Invariants

These three rules are non-negotiable:

• Do not execute mutate commands until a prescribe tool returns ok=true with prescription_id.
• Every prescribe must have exactly one report.
• Always include actor.skill_version (set to this contract version).

Breaking these invariants triggers protocol violation signals that degrade your reliability score.

What Requires Prescribe/Report

Mutate operations (MUST use protocol)

Contract classification:

Mutation examples (must use prescribe/report):

• kubectl apply/delete/patch/create/replace/rollout restart
• helm install/upgrade/uninstall/rollback
• terraform apply/destroy/import

Read-only examples (skip protocol):

• kubectl get/describe/logs/top/events
• helm list/status/template
• terraform plan/show/output

When unsure whether a command mutates state, call `prescribe_smart`. It's always safe to prescribe — the cost is one extra call. The cost of skipping is a protocol violation signal.

Calling The Prescribe Tools

Recommended default: prescribe_smart

Record lightweight intent BEFORE an infrastructure operation that creates, modifies, or deletes resources. Use this tool when you know the tool, operation, and target resource but do not have artifact bytes.

{
  "tool": "kubectl",
  "operation": "apply",
  "resource": "deployment/web",
  "namespace": "default",
  "actor": {
    "type": "agent",
    "id": "your-agent-id",
    "origin": "mcp-stdio",
    "skill_version": "1.1.0"
  }
}

Use prescribe_smart when you know the target resource and namespace but do not need artifact-level drift detection.

Required inputs:

• tool
• operation
• resource
• actor (type, id, origin)

Smart pre-call checklist

• tool/operation must be non-empty.
• resource must identify the target (for example deployment/web).
• actor.type/actor.id/actor.origin must be present.
• actor.skill_version should be set to this contract version.
• Keep session/operation/trace identifiers stable within one task.

prescribe_full

Record full artifact intent BEFORE an infrastructure operation that creates, modifies, or deletes resources. Use this tool when you have the actual artifact bytes and want native detector coverage plus artifact drift tracking.

{
  "tool": "kubectl",
  "operation": "apply",
  "raw_artifact": "<the full YAML/JSON/command content>",
  "actor": {
    "type": "agent",
    "id": "your-agent-id",
    "origin": "mcp-stdio",
    "skill_version": "1.1.0"
  }
}

Use prescribe_full when you have the artifact bytes and want native detector coverage plus artifact drift detection.

Required inputs:

• tool
• operation
• raw_artifact
• actor (type, id, origin)

Full pre-call checklist

• tool/operation must be non-empty.
• raw_artifact must contain the artifact or command content being executed.
• actor.type/actor.id/actor.origin must be present.
• actor.skill_version should be set to this contract version.
• Keep session/operation/trace identifiers stable within one task.

Optional but recommended fields

{
  "session_id": "stable-session-id",
  "operation_id": "unique-per-operation",
  "environment": "production",
  "scope_dimensions": {
    "cluster": "prod-us-east-1",
    "namespace": "default"
  }
}

Keep session_id stable within one task. Use scope_dimensions to provide cluster/namespace/account/region context.

What the prescribe tools return

{
  "ok": true,
  "prescription_id": "01ABC...",
  "risk_inputs": [
    {
      "source": "evidra/native",
      "risk_level": "high",
      "risk_tags": ["k8s.privileged_container"]
    }
  ],
  "effective_risk": "high",
  "artifact_digest": "sha256:...",
  "intent_digest": "sha256:...",
  "operation_class": "mutate",
  "scope_class": "production",
  "resource_count": 1
}

Returns:

• prescription_id (required for report)
• risk_inputs, effective_risk
• artifact_digest, intent_digest
• resource_shape_hash, operation_class, scope_class

If a prescribe tool fails

If `prescribe_full` or `prescribe_smart` returns ok=false, do not execute the infrastructure command. Investigate the error before retrying.

The error codes are:

• parse_error — the artifact couldn't be parsed (check format)
• invalid_input — required fields are missing
• internal_error — server-side issue

Executing the Command

After a prescribe tool returns ok=true, execute the infrastructure command normally. Capture:

• The exit code (0 for success, non-zero for failure)
• Whether any error occurred

Calling Report

Record the terminal verdict AFTER an infrastructure operation completes or is intentionally declined.

Success

{
  "prescription_id": "01ABC...",
  "verdict": "success",
  "exit_code": 0,
  "actor": {
    "type": "agent",
    "id": "your-agent-id",
    "origin": "mcp-stdio",
    "skill_version": "1.1.0"
  }
}

Failure

{
  "prescription_id": "01ABC...",
  "verdict": "failure",
  "exit_code": 1,
  "actor": { "type": "agent", "id": "your-agent-id", "origin": "mcp-stdio", "skill_version": "1.1.0" }
}

Always report failures with the actual non-zero exit code. Hiding failures triggers artifact drift and protocol violation signals.

Declined (intentional refusal)

When you decide not to execute after prescribing (e.g., risk is too high):

{
  "prescription_id": "01ABC...",
  "verdict": "declined",
  "decision_context": {
    "trigger": "risk_threshold_exceeded",
    "reason": "Critical risk: privileged container in production"
  },
  "actor": { "type": "agent", "id": "your-agent-id", "origin": "mcp-stdio", "skill_version": "1.1.0" }
}

Note: exit_code is forbidden for declined verdicts. Use decision_context instead.

Terminal outcome rule

• Every prescribe must end with exactly one report, including failed, errored, aborted, or declined attempts.
• Retries require a new prescribe/report pair for each attempt.

Rules

• Always report failures; do not hide non-zero exit codes.
• Always report deliberate refusals with a concise operational reason.
• Do not report twice for the same prescription_id.
• Do not report another actor's prescription_id.
• If prescription_id is lost, call a prescribe tool again before execution.
• Actor identity should match the original prescribe actor.
• Include actor.skill_version for behavior slicing.
• exit_code is required for success/failure/error verdicts and forbidden for declined verdicts.
• On retry, call a prescribe tool again to get a new prescription_id before re-executing. Each attempt is a separate prescribe/report pair.

What report returns

{
  "ok": true,
  "report_id": "01DEF...",
  "verdict": "success",
  "score": 95.5,
  "score_band": "excellent",
  "signal_summary": {
    "protocol_violation": 0,
    "artifact_drift": 0,
    "retry_loop": 0,
    "blast_radius": 0,
    "new_scope": 0,
    "repair_loop": 0,
    "thrashing": 0,
    "risk_escalation": 0
  }
}

The score (0-100) reflects your operational reliability within the current session. Non-zero signals indicate behavioral patterns that reduce trust.

Retry Handling

When retrying a failed operation:

1. Call prescribe_full again if you still have artifact bytes, or prescribe_smart again if you do not
2. Execute the command
3. Call report with the new prescription_id

Each attempt gets its own prescribe/report pair. Do not reuse a previous prescription_id.

Risk Tags Reference

Prescribe may return risk tags indicating specific concerns detected in the artifact:

Kubernetes

Docker/Compose

Terraform (AWS)

Operations (cross-tool)

Behavioral Signals

Evidra monitors eight behavioral signals. Understanding them helps you maintain a high reliability score:

• protocol_violation — Missing report for a prescribe, or executing without prescribing
• artifact_drift — The artifact you actually applied differs from what you prescribed
• retry_loop — Same intent retried multiple times (may indicate a loop)
• blast_radius — Large number of resources affected (>5 in non-production)
• new_scope — First operation in a production scope
• repair_loop — Repeated failure-then-fix cycles in a session
• thrashing — Rapid create/delete oscillation on the same resources
• risk_escalation — Operations exceeding the originally prescribed risk level

Setup

MCP Configuration (Claude Code / Claude Desktop)

Add to your MCP config (e.g., ~/.claude.json or Claude Desktop settings):

{
  "mcpServers": {
    "evidra": {
      "command": "evidra-mcp",
      "args": ["--evidence-dir", "~/.evidra/evidence", "--environment", "production"]
    }
  }
}

For development with optional signing:

{
  "mcpServers": {
    "evidra": {
      "command": "evidra-mcp",
      "args": ["--evidence-dir", "~/.evidra/evidence", "--signing-mode", "optional"]
    }
  }
}

Docker

docker run -v ~/.evidra/evidence:/evidence \
  -e EVIDRA_EVIDENCE_DIR=/evidence \
  -e EVIDRA_ENVIRONMENT=production \
  evidra-mcp

Environment Variables

Quick Decision Flowchart

Is this an infrastructure command?
├─ No  → Just execute it. No protocol needed.
└─ Yes → Does it mutate state?
         ├─ No  (get/describe/logs/plan/show) → Execute directly.
         ├─ Yes (apply/delete/create/destroy)  → prescribe → execute → report
         └─ Unsure → prescribe → execute → report (safe default)