A read-only Assay policy toolkit for checking MCP tool calls against policy before they run.
Validate arguments (assay_check_args) — check a tool's arguments against a policy schema for a given tool.
Check call sequences (assay_check_sequence) — decide whether a next tool call is allowed given prior history and a policy.
Rule on a single tool (assay_policy_decide) — ask whether a tool is blocked by a policy.
Analyze trace coverage (assay_check_coverage) — compare recorded traces (tools, rules triggered) against a policy, with optional threshold and JSON/Markdown/GitHub output.
Explain evaluations (assay_explain_trace) — produce a human-readable explanation of a trace's evaluation against a policy in JSON, Markdown, terminal, or HTML.
All tools return decisions/explanations only — no enforcement, execution, or evidence-bundle production happens here.
Integrates with GitHub Actions to block PR regressions through Trust Basis diffs and produce SARIF/JUnit-ready output for policy gates.
Agents got real tool access through MCP — and tool poisoning, rug pulls, and confused-deputy OAuth came with it. Most tools scan a server or filter a prompt. Assay sits at the tool-call boundary and does three things, in order.
One golden path: the release-pinned agent journey records the nine driven CLI/MCP steps and their exit/stdout contracts. Its protected-action fixture lives in examples/privileged-action-gate/.
Enforce. A deterministic, fail-closed gate decides every tools/call before it runs, with the precise reason for each allow or deny. On Linux it adds real kernel enforcement — an eBPF/LSM IPv4/TCP connect-egress block and a Landlock TCP-connect port allowlist, both opt-in and fail-closed. A policy it cannot express exactly is refused, never half-applied.
Prove. Each decision and observed effect becomes an offline-verifiable, tamper-evident evidence bundle: the verdict, the pre-call establish journey, and declared-vs-observed conformance — all reviewable in CI, with no hosted backend.
Stay honest. Every claim carries its basis (verified, self_reported, inferred, absent), and a gate refuses to let a claim exceed what was observed. A tool returning "success" is the provider's assertion, never proof. Assay ships no single safety score and never claims more than it can prove.
# Fast path: release installer for Linux and macOS.
curl -fsSL https://getassay.dev/install.sh | sh
# Confirm the command resolves; if setup fails, run `assay doctor`.
assay --version
# Source-build alternative (requires Rust):
cargo install assay-cli --version 6.2.1 --locked
python3 examples/mcp-quickstart/run.pyFor v6.2.1, run the last command from a source checkout or an extracted published CLI archive.
The installer is binary-only and does not carry the bounded quickstart assets. The live
getassay.dev installer verifies the selected archive against its published SHA-256 sidecar before
extraction. Set ASSAY_REQUIRE_PROVENANCE=1 to additionally require GitHub artifact provenance;
the default reports provenance_not_requested and strict success reports provenance_verified.
A checksum proves byte equality with the published sidecar, not producer identity. Provenance
identifies the source and build, not runtime safety or semantic correctness.
Captured runner output (the bundled local mock performs no external action):
assay quickstart: PASS
mcp_requests=initialize,tools/list,tools/call
decision=allow tool=read_file
decision_artifact=.assay/quickstart/decisions.ndjson
non_claim=forwarded_to_local_mock_only
Released surfaces:
Static project manifests are shipped for Claude Code and Cursor; Codex uses the equivalent TOML entry documented in the editor MCP recipe. Manifest presence is not host-discovery proof. assay mcp config-path supports Claude and Cursor only.
Published v6.2.1 CLI archives cover Linux x86_64/arm64, macOS x86_64/arm64, and Windows x86_64. The Python wheels cover CPython 3.12 on macOS x86_64/arm64 and Linux x86_64; other interpreters and platforms are not claimed.
Published assay-mcp-server archives cover Linux x86_64/arm64. MCPB and server.json package descriptors are also published; their presence is not host-discovery proof.
CI: GitHub Action. Core flows need no hosted backend or API key. New to the threat model? The OWASP MCP Top 10 mapping states, per risk, what Assay covers and deliberately does not.
Output | What it is |
Policy gate |
|
Evidence bundle | Offline-verifiable, tamper-evident archive for audit and replay. |
Trust Basis / Trust Card | Canonical |
External receipts | Eval outcomes, runtime decisions, and model inventory as bounded receipts with JSON Schema contracts. |
Tool-decision surface | Each privileged |
SARIF / CI | GitHub Action, Security-tab integration, policy gates on PRs. |
Attestation | Sign an evidence bundle as a DSSE-wrapped in-toto v1 Statement with the evidence-bundle/v1 predicate. |
Agent ──► Assay ──► MCP Server
├─ ✅ ALLOW / ❌ DENY (policy, with reason)
├─► 📋 Evidence bundle (offline-verifiable)
└─► 📊 Trust Basis → Trust Card → SARIF / CICurrent release: v6.2.1. CHANGELOG.md and release notes remain the authority for released behavior; merged changes after the tag are Unreleased, and crates.io publication is separate from merge state.
Related MCP server: governed-mcp
Yes if you already have eval output, runtime decisions, inventory artifacts, or MCP tool-call tests, and you want a small reviewable CI artifact instead of a dashboard — bounded auditability, not a scalar trust badge.
Not yet if you need Assay to judge model correctness for you, want a hosted dashboard as the product, or want a compliance claim rather than a bounded evidence boundary. Assay is not a trust-score engine, a generic eval dashboard, or a hosted observability product — see what it is and is not.
An agent tries a privileged action — github.add_deploy_key — through the enforcing proxy, decided per call before it forwards, offline against a local mock (no real credentials):
cd examples/privileged-action-gate && ./run.sh
A deny is fail-closed caution, not a verdict on intent; an allow is the decision to forward, never proof the action happened. Declared-vs-observed conformance is recorded beside the verdict, never as a gate. Full walkthrough: privileged-action-gate.
You have | What you get | Start here |
Promptfoo JSONL from CI evals | Eval outcome receipts + verified bundle + Trust Basis diff | |
OpenFeature | Decision receipt + verified bundle | |
CycloneDX ML-BOM model component | Inventory receipt + verified bundle | |
MCP tool calls | Allow/deny audit trail + observed-behavior evidence | |
A GitHub PR gate | Trust Basis diff, gate status, SARIF/JUnit-ready output | |
A Runner archive / coverage annotation | Coverage descriptors + claim-class cells + a claimed-vs-observed check |
The workflow stays small: import or record a bounded outcome, bundle and verify it, compile trust-basis.json, gate the Trust Basis diff. Assay doesn't make the upstream tool the source of truth; it makes the evidence boundary inspectable. For privileged tool actions, the MCP proxy records each tools/call as a structured tool-decision surface — keeping the asserted-versus-verified line honest.
version: "2.0"
name: "my-policy"
tools:
allow: ["read_file", "list_dir"]
deny: ["exec", "shell", "write_file"]
schemas:
read_file:
type: object
properties:
path: { type: string, pattern: "^/app/.*" }
required: ["path"]assay init --from-trace trace.jsonl generates the runtime-observation policy used by the trace-generation flow (files, network, and processes); it is not an MCP authorization policy. Migrate a legacy MCP constraints: policy with assay policy migrate. See Policy Files.
Canonical evidence | Assay's evidence model is the stable contract; OpenTelemetry and protocol adapters (ACP / A2A projection profile / UCP) map into it. |
Deterministic | Same input, same decision — not probabilistic. |
Bounded claims | Explicit about verified vs visible vs absent — no score-first UX. |
Offline-first | No backend required for core enforcement and bundle verification. |
Checkable provenance | Which piece of the source-class and coverage model shipped when, as commits you can |
MCP Quickstart · Editor MCP recipe — policy-enforcing MCP in Cursor / Claude Code / Codex
MCP 2025/2026 protocol-era parity — pinned resultType and interim-result compatibility corpus
Coding-agent governance · OpenTelemetry & Langfuse — observed runs → evidence
Evidence Receipts in Action — Promptfoo / OpenFeature / CycloneDX receipt families
CI Guide · Evidence Store (S3 / B2 / MinIO)
Trust claims use explicit epistemology, not a single safety score: verified (direct evidence or offline verification), self_reported (emitted without independent corroboration), inferred (bounded, documented rules), absent (no trustworthy evidence). Assay ships no aggregate trust score or safe/unsafe badge as the main output — see ADR-033.
Tool-decision path latency on an M1 Pro fragmented-IPI harness: main protection 0.771ms p50 / 1.913ms p95; fast-path 0.345ms p50 / 1.145ms p95. These are tool-decision timings, not end-to-end model latency.
Assay-Runner is an internal measured-run subsystem behind the delegated Linux/eBPF acceptance path — publish = false, not a standalone product, no release commitment.
Repositories that compose with Assay's evidence layer:
assay-action — GitHub Action: verify bundles, PR summaries, SARIF (Marketplace).
Assay-Harness — recipe, gate, and report layer over canonical evidence artifacts.
observed-effect-v0 — worked examples of the bounded observed-effect evidence record and its neutral carriers (in-toto, SCITT, MCP evidenceRef).
gateway-evidence-replay — deterministic offline replay verifier for gateway-path evidence bundles.
RGE-Bench — a conformance kit for evidence reviewability, maintained separately under its own machine-checked neutrality guard. Reproduction there is digest-scoped and does not carry forward: the v1 71-vector digest sha256:e769822bc6c9e31085da7b1a17b163b9747fe0d04314fbb8685d4e612087c7cb and the current v2 digest sha256:ba0e3795d75c788fa48313ab462493f22d78759851d1b3275d8117051bb22fd0 (95 vectors) each carry one reported independent implementation by a second author on a different stack. JM-Lab reported the v2 95/95 reproduction on 2026-08-24, from the contract text and author-supplied inputs without reading expected. See its REPRODUCTIONS.md.
privileged-mcp-action/v0
is a composition and verification contract over evidence records that already exist: what a
privileged MCP tool call decided, what was observed of its effect, and what stays unproven. It adds
no new envelope and no aggregate verdict.
It ships with a 14-vector conformance corpus (5 accept, 9 reject) whose digest is a candidate: it is not called reproduced until a non-author implementation derives the expected outcomes from the specification text alone.
That reproduction is open, and the invitation is real: #1840. Any language, any stack. The invitation names the exact commit the current digest describes. The clean-room protocol provides an opaque, attested inputs pack, a one-command scoring action, and an implementation-report template without supplying verifier logic or expected outcomes. The corpus README states the authorship boundary and the claim ceiling.
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warningsSee CONTRIBUTING.md and GitHub Discussions.
Validate tool arguments against a policy schema.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | ||
| policy | No | ||
| arguments | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It merely states 'validate tool arguments' without any details on side effects, return behavior on success/failure, authentication needs, or rate limits. Since the tool performs validation, the description should at least hint at whether it returns a boolean, throws errors, or has any side effects. The current description lacks this essential transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of a single sentence. While this is efficient and front-loaded, it may be too terse for a tool with three parameters (including a nested object) and no output schema. The description earns its place by being clear about the overall action, but it could be slightly expanded to include essential details without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (three parameters, nested object, no annotations, no output schema), the description is incomplete. It fails to describe the output/return value, which is critical for an agent to know how to use the tool. Additionally, it does not explain the relationship between parameters or provide any behavioral context. The description leaves significant gaps that could hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter documentation. The description adds minimal context: it mentions 'tool arguments' and 'policy schema', implying that 'arguments' is the object to validate and 'policy' is the schema to validate against. However, it does not explain the 'tool' parameter or provide details on the structure of 'arguments' or 'policy'. Given the low coverage, the description should compensate with more detailed parameter semantics, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Validate tool arguments against a policy schema.' It uses a specific verb ('validate') and resource ('tool arguments'). This clearly distinguishes it from sibling tools like assay_check_coverage, which check coverage, and assay_check_sequence, which check sequences. The purpose is unambiguous and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not specify prerequisites, when validation is needed, or how it fits into a workflow. For example, it doesn't say whether this should be called before invoking another tool or as a standalone check. This omission leaves the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze trace coverage against a policy.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | ||
| policy | Yes | ||
| traces | Yes | ||
| threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description fully carries the burden of behavioral disclosure. It does not mention side effects, permissions, return format, or any behavioral traits. The word 'analyze' implies read-only, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise. However, it is under-specified for a tool with 4 parameters; it trades substance for brevity. While efficient in word count, it lacks the necessary structure and detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, 2 required, no output schema, and no annotations, the description is completely inadequate. It does not explain parameters, return values, or behavioral context, making it impossible for an agent to use the tool effectively without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain what each parameter means. The description only provides the tool's high-level purpose and gives no information about 'policy', 'traces', 'threshold', or 'format'. This leaves the agent with no understanding of how to correctly fill the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('analyze') and the resource ('trace coverage against a policy'), which is specific enough to understand the tool's main function. However, it does not differentiate from sibling tools like assay_check_args or assay_check_sequence, which also check aspects of assay policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as assay_check_args or assay_check_sequence. Without context on coverage vs. args/sequence, an agent cannot decide which tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate if a tool call is allowed given the history.
| Name | Required | Description | Default |
|---|---|---|---|
| policy | No | ||
| history | Yes | ||
| next_tool | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It does not mention side effects, permissions, rate limits, or any constraints beyond the stated purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one sentence, which is too short to provide adequate information for a tool with 3 parameters and no other documentation. It is under-specified, not appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and a complex task (validation logic), the description is completely inadequate. It does not explain what 'allowed' means, what the parameters do, or what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters (history, next_tool, policy) but the description mentions none of them. Schema coverage is 0%, so the description should compensate, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Validate if a tool call is allowed given the history' clearly states the verb 'validate' and the resource 'tool call allowed'. However, it does not differentiate from sibling tools like assay_check_args, which likely validates arguments, so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no explicit context or exclusions. It only states the general purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain trace evaluation against a policy
| Name | Required | Description | Default |
|---|---|---|---|
| trace | Yes | ||
| format | No | ||
| policy | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral traits disclosed; no annotations provided. Description does not mention return value, side effects, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise (single sentence) but lacks structure; could benefit from additional context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description is severely incomplete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds no details about parameters; only implies policy and trace are inputs without explaining their roles or the format parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool explains trace evaluation against a policy, distinguishing it from sibling tools focused on checking or deciding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like assay_policy_decide or assay_check_sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if a tool is blocked by policy.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | ||
| policy | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden but only states it checks blocking status. It fails to disclose whether the tool modifies state, requires authentication, or has side effects, leaving behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is too sparse to be fully effective; it earns high marks for brevity but loses a point for sacrificing necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema and annotations, the description is insufficient for an agent to understand return values, error conditions, or interpretation of 'blocked' status, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain what 'tool' or 'policy' parameters represent, leaving the agent with no semantic guidance for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' and identifies the resource 'if a tool is blocked by policy', clearly differentiating from sibling tools that check arguments, coverage, sequence, or traces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided; the description does not indicate when to use this tool over siblings or mention any prerequisites or context for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0assay_check_argsassay_check_coverageassay_check_sequenceassay_explain_traceassay_policy_decideScored across 5 tools
Each tool targets a distinct aspect of policy analysis: argument validation, coverage, sequence validation, trace explanation, and policy decision. No overlap in purpose.
All tools follow the consistent pattern 'assay_<verb>_<noun>', using snake_case throughout. The prefix 'assay_' unifies the set.
Five tools is a well-scoped set for a policy analysis server. Each tool serves a clear role without redundancy, covering the core operations.
The tools cover essential policy checking operations (validate args, check coverage, sequence validation, explain traces, decide policy). Missing a tool to list or retrieve policies, but the set is otherwise solid for its domain.
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Hosted MCP server for AI agent identity, permissions, verification, and reusable proof.
Tamper-evident proof creation and verification for AI agents via MCP, A2A, and REST.