A stdio Model Context Protocol server that lets AI coding agents (Claude Code, Cursor, Codex, OpenHands, …) read a repository's DECIONIS_POLICY.md and evaluate candidate actions before they commit, deploy, or migrate anything.

It is not a re-implementation: decionis_evaluate boots the real @decionis/protocol service in-process with an in-memory store, publishes the repo policy through the protocol's own schema-validated bundle ingestion, and evaluates through POST /v1/protocol/evaluate-decision via fastify inject(). The verdict an agent sees locally is the verdict the platform would produce — with zero network, zero database, zero credentials, and nothing recorded.

(The protocol service separately exposes a remote, authenticated MCP surface for org-connected agents; this package is the local, offline complement for repo checkouts.)

The package now exposes two complementary surfaces:

MCP tools let the model read policy, evaluate an intended action, and understand the verdict vocabulary.
Native PreToolUse hooks intercept every supported tool call outside the model's discretion. Codex, GitHub Copilot, and Claude Code all normalize into one AgentToolCall contract and one AgentGateEvaluator interface.

MCP is the discovery and explanation surface. The native hook is the binding enforcement surface.

Tools

Tool	Purpose
`decionis_read_policy`	Path, sha256, and compiled rules (or compile errors) of the repo's `DECIONIS_POLICY.md`.
`decionis_evaluate`	Evaluate a candidate action payload against the policy through the real evaluator; returns the verdict + matched rule.
`decionis_demo`	The one-minute demo: four canned intents through the real evaluator with a built-in sample policy — one per wire outcome. No account, no key, no policy file, no network, nothing recorded.
`decionis_verdict_help`	The verdict vocabulary, rules-block grammar, and how an agent should behave on each verdict.

All four are read-only, credential-free, and networkless (readOnlyHint: true, openWorldHint: false) — an agent host that gates side-effectful tools behind approval has nothing to gate here. The shield.* tools register only when DECIONIS_SHIELD_API_KEY and DECIONIS_SHIELD_APP_ID are configured.

Kubernetes execution-authority tools

The optional Kubernetes tools add a client-side gate while the validating admission webhook remains the independent cluster-side gate:

Tool	Purpose
`k8s_plan`	Resolve exact objects and show only digests, action hashes, diffs, and bounded facts.
`k8s_request_authority`	Request ALLOW/HOLD/BLOCK and signed dossier references without applying.
`k8s_apply`	Consume an exact Decionis grant, then stream the bound object snapshot to Kubernetes.
`k8s_scale`	Consume an exact scale grant, then submit that bound scale object, including scale-to-zero.
`k8s_rollback`	Apply an exact, existing-target rollback manifest after authority; vague undo is rejected.
`k8s_verify_dossier`	Independently verify the dossier proof bundle and Ed25519 evidence.

Enable them explicitly. The process uses the selected local kube context without reading or exporting kubeconfig credentials:

DECIONIS_KUBERNETES_TOOLS_ENABLED=true
DECIONIS_AUTHORITY_BASE_URL=https://api.decionis.example
DECIONIS_API_KEY=<org-scoped-key>
DECIONIS_ORG_ID=<org-uuid>
DECIONIS_KUBERNETES_CLUSTER_ID=production-eu-1
DECIONIS_KUBERNETES_ACTOR=operator@example.com
DECIONIS_KUBERNETES_POLICY_VERSION=kubernetes-production-v1
DECIONIS_KUBERNETES_CONTEXT=production-eu-1

DECIONIS_KUBERNETES_VERIFICATION_ORIGINS may add comma-separated HTTPS origins for dossier/JWKS verification. Arbitrary origins are rejected. Mutating tools fail closed on authority, dossier, action-hash, grant, or Kubernetes errors; a Kubernetes command failure requires fresh authority because the single-use client grant has already been consumed.

The policy file resolves from the tool's path argument, then $DECIONIS_POLICY_PATH, then ./DECIONIS_POLICY.md in the working directory.

Install

Claude Code — as a plugin (one command, gate included):

/plugin marketplace add decionis/mcp
/plugin install decionis

That installs the MCP tools and the binding PreToolUse gate together. Then, in a repository you want governed:

/decionis:init

…which writes a starter DECIONIS_POLICY.md. Ask your agent to run rm -rf /var/lib/postgresql and it comes back refused, by rule name.

A repository with no DECIONIS_POLICY.md is simply not governed — the plugin runs everywhere, so it does not gate projects that never opted in. A policy that exists but cannot be compiled still fails closed.

Everything else:

npm install -g @decionis/mcp

Or skip the install entirely — every client config below can launch the server through npx -y @decionis/mcp.

Wire it up

Claude Code — .mcp.json at the repo root:

{
  "mcpServers": {
    "decionis": {
      "command": "npx",
      "args": ["-y", "@decionis/mcp"]
    }
  }
}

Codex — add the stdio server to ~/.codex/config.toml or a trusted project's .codex/config.toml:

[mcp_servers.decionis]
command = "npx"
args = ["-y", "@decionis/mcp"]
required = true

Cursor — use the Claude server block in .cursor/mcp.json. During development, "command": "pnpm", "args": ["--filter", "@decionis/mcp", "dev"] also works.

Source checkout — build once (pnpm --filter @decionis/mcp build) and point the client at the bin directly: "command": "node", "args": ["<repo>/apps/mcp/dist/index.js"].

Native execution gate

Install the package globally so decionis-agent-hook (and the other bins) land on the host's PATH:

npm install -g @decionis/mcp

Copy the provider template to its native repository location:

Host	Template	Native location
Codex	`templates/CodexHooks.json`	`.codex/hooks.json`
Claude Code	`templates/ClaudeSettings.json`	`.claude/settings.json`
GitHub Copilot CLI/cloud agent/VS Code	`templates/CopilotHooks.json`	`.github/hooks/Decionis.json`

For a source checkout, replace the template's decionis-agent-hook … command with:

node "$(git rev-parse --show-toplevel)/apps/mcp/dist/AgentHookCli.js" <provider>

where <provider> is codex, copilot, or claude.

Evaluation modes

The hook defaults to local mode. It loads DECIONIS_POLICY.md, publishes it into the real in-process protocol evaluator, and enforces the result without network access or credentials.

Set these variables to use the enterprise policy graph and signed decision pipeline:

DECIONIS_AGENT_GATE_MODE=remote
DECIONIS_AGENT_GATE_URL=https://protocol.decionis.com/v1/protocol/evaluate-decision
DECIONIS_API_KEY=<org-scoped-key>
DECIONIS_ORG_ID=<org-uuid>

DECIONIS_AGENT_GATE_TIMEOUT_MS optionally changes the remote request timeout (default: 4 seconds). Partial remote configuration is rejected; network errors, invalid hook input, missing policy, and evaluator failures all produce a native deny response.

An APPROVE result returns no permission override, so the host's normal sandbox and user approval flow still applies. REJECT, REVIEW, and ESCALATE all stop the tool call; the latter two remain blocked until a human resolves them through the policy workflow.

Reusable interface

Other runtimes can import the same contracts and orchestration layer:

import {
  AgentHookRunner,
  type AgentGateEvaluator,
  type AgentHostAdapter,
  type AgentToolCall,
} from "@decionis/mcp/agent";

A new provider implements only AgentHostAdapter; a new decision backend implements only AgentGateEvaluator. Neither needs to understand the other provider formats.

For pre-prompt enforcement, @decionis/sdk exposes the complementary DecionisAgentTaskGateway interface. It reserves the model budget before an OpenAI or Anthropic proxy call, verifies sandbox egress, consumes the same bound grant at the proxy, and reconciles provider usage. Copilot embeddings use the same reserve/egress/reconcile contract when model transport itself is not replaceable.

See docs/integrations/agents/AgentBoundaryGateway.md for the provider SDK configuration and four-boundary deployment model.

Managed distribution

Device-management templates are under templates/managed:

CodexRequirements.toml pins the managed PreToolUse hook in requirements.toml.
CopilotPolicyHooks.json is the root-owned Copilot CLI policy hook; cloud agent continues to use the repository template.
ClaudeManagedSettings.json is the organization-controlled Claude Code settings fragment.
AgentPolicyBundle.json is a fail-closed, source-dated policy-graph skeleton. It contains explicit official list-price cards retrieved on 2026-07-27. Negotiated rates are stored separately under the organization policy's agentExecution.providerContracts; a contract overrides the public baseline only while it is effective and independently maker-checker approved.
AgentGateConfig.example.json documents the protected, org-scoped runtime configuration. The package never embeds its API key.

Build the deterministic deployment ZIP with:

pnpm --filter @decionis/mcp package:managed

The ZIP contains Linux, macOS, and Windows payload trees, the bundled managed runner, native policy files, the organization policy template, an install manifest, and SHA256SUMS. Codex executes the runner from its declared managed hook directory. Render the example runtime configuration at the manifest destination, protect it with administrator-only permissions, and distribute the matching payload through the organization's package or device-management system.

Host boundaries

PreToolUse happens after the host has already spent tokens choosing a tool. It prevents the side effect, but it cannot prevent the model cost incurred before that point. Put the Decionis API/network gateway in front of model traffic when pre-prompt token and cost reservation is required.
Codex hooks cover shell commands, apply_patch, MCP calls, and supported local function tools. Hosted tools that do not traverse the local hook path need a separate gateway boundary.
Copilot command-hook timeouts are fail-open at the host level. Keep the Decionis request timeout below the hook timeout (the defaults are 4 seconds and 10 seconds) and deploy the executable inside the cloud-agent image.
Copilot cloud agent requires the Decionis endpoint to be permitted by its network firewall when remote mode is used.
VS Code agent hooks are currently a preview surface. VS Code reads the same .github/hooks/*.json template, emits the PascalCase-compatible snake-case payload, and receives the nested native denial shape from the adapter.
Copilot's userPromptSubmitted event is observational and cannot block prompt processing. Copilot pre-prompt spend enforcement therefore belongs at the enterprise proxy/API boundary, not in a repository hook.
Hook inputs may contain secrets inside commands or tool arguments. The gate evaluates them in memory and does not log them.

Registries & discovery

Where machines find these surfaces without reading this README:

/.well-known/mcp.json — both MCP surfaces (this stdio package and the hosted https://protocol.decionis.com/mcp streamable-HTTP server), their tools, and how each authenticates.
/.well-known/openapi.json — the published REST contract the hosted surfaces sit on.
Registry manifests — server.json (official MCP registry, namespace com.decionis/mcp; package.json carries the matching mcpName), smithery.yaml, and glama.json live next to this file. Submission steps: docs/marketplace/mcp-registries.md in the monorepo.
Registry release automation — after the matching npm package is public, the repository's Publish MCP Registry Entry workflow authenticates the com.decionis namespace, publishes this metadata, and verifies the exact version through the public registry API.

Development

pnpm --filter @decionis/mcp test        # vitest (includes the real evaluator)
pnpm --filter @decionis/mcp typecheck
pnpm --filter @decionis/mcp build       # self-contained dist/index.js (shebang bin)
pnpm --filter @decionis/mcp package:managed

Smoke test over stdio:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"decionis_evaluate","arguments":{"payload":{"action":"production-deploy","change_freeze":true}}}}' \
  | node dist/index.js

Notes

The rules-block compiler here mirrors apps/api/src/services/policyEncoding/decionisRulesBlock.ts and must stay in lockstep (local difference: JSON-only block bodies; the platform also accepts YAML).
Rules without "domain": "*" are filtered by the platform's decision-domain match — the evaluate tool detects this and tells the agent how to fix the policy.
Local evaluations mint no signed Decision Dossier; CI runs through decionis/govern produce the verifiable record.