@decionis/mcp — agent policy tools and execution hooks

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_verdict_help | The verdict vocabulary, rules-block grammar, and how an agent should behave on each verdict. |

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

Install

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

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.