assay

Assay is an open-source evidence and policy enforcement proxy for MCP (Model Context Protocol) tool calls, officially positioned as an "open, recomputable evidence record for privileged MCP tool actions." It sits at the tool-call boundary and does three things in order: enforce, prove, and stay honest.

I. Purpose and Background According to official materials, agents gain real tool access through MCP, and with that come risks such as tool poisoning, rug pulls, and confused-deputy OAuth. Assay is intended to let reviewers offline replay what a given privileged tool call "decided, observed, and what remains unproven," rather than simply trusting the agent's own statements about itself.

II. Main Capabilities

1. Enforce: In enforcement mode, MCP tools/call requests passing through the proxy are judged as allowed or denied before forwarding, with a precise reason given for each allow or deny. This proxy gate is deterministic and fail-closed; the enforcement proxy is a reference producer, not the contract itself. On supported Linux hosts, optional controls include: cgroup eBPF IPv4/TCP connect filtering (whose hook error path allows the connection), and a Landlock TCP connection port allowlist. assay sandbox --enforce will refuse to execute when the backend is unavailable or filesystem policies conflict, unless --allow-audit-fallback is explicitly used. --enforce-net must be paired with --enforce; active Landlock network enforcement will reject policies that cannot be expressed as a TCP port allowlist, even when audit fallback is enabled.
2. Prove: Configurable producers can record decisions and bounded observations, and export them as offline-verifiable, tamper-evident evidence bundles. The privileged action flow carries the decision result, the pre-call journey establishment, and the consistency between claims and observations, for CI review without a hosted backend. Note: the basic assay mcp wrap does not automatically create evidence bundles; the required recording and export steps must be enabled.
3. Stay honest: Trust Basis classifies supported claims as verified, self_reported, inferred, or absent, and its gate checks the boundaries of claims. The tool returns ""success" is only the provider's assertion, and never equals proof. Assay does not provide a single security score; before relying on any artifact, you should read its source, coverage, and undeclared matters.

III. Usage and Workflow The workflow stays lean: import or record a bounded result, package and verify it, compile trust-basis.json, and gate on Trust Basis differences. Assay does not let upstream tools become the source of truth, but instead makes the evidence boundary inspectable. For privileged tool actions, the MCP proxy records each tools/call as a structured tool decision surface, keeping the line between "assertion and verification" clear.

Version and installation points: For v6.12.0, the last command must be run after checking out from source or extracting the released CLI archive; the installer is binary-only and does not include the bounded quickstart assets. The online getassay.dev installer verifies the selected archive against the published SHA-256 sidecar before extraction. Setting ASSAY_REQUIRE_PROVENANCE=1 additionally requires GitHub artifact provenance; by default it reports provenance_not_requested, and on strict success it reports provenance_verified. Checksum attestation matches the bytes of the published sidecar, not the producer identity; provenance identifies origin and build, not runtime security or semantic correctness.

On policy: assay init --from-trace trace.jsonl generates the runtime observation policy (files, network, processes) used by the trace generation workflow; it is not an MCP authorization policy. Legacy MCP constraints policies can be migrated with assay policy migrate.

Released forms: static project manifests are provided for Claude Code and Cursor; Codex uses the equivalent TOML entries documented in the editor MCP recipe. The existence of a manifest does not equal proof of host discovery. assay mcp config-path supports only Claude Desktop and Cursor. The v6.12.0 CLI archive covers Linux x86_64/arm64, macOS x86_64/arm64, Windows x86_64; Python wheels cover macOS x86_64/arm64 and Linux x86_64 for CPython 3.12, 3.13, and 3.14; no claims are made for other interpreters and platforms. The assay-mcp-server archive covers Linux x86_64/arm64. MCPB and server.json package descriptors have also been published; their existence does not constitute proof of host discovery. CI provides a GitHub Action, and the core workflow requires no hosted backend or API key.

IV. Applicable Scenarios Suitable for: users who already have evaluation outputs, runtime decisions, manifest artifacts, or MCP tool call tests, and want small, reviewable CI artifacts rather than a dashboard, pursuing bounded auditability rather than a single trust badge. Not suitable for: users who need Assay to determine model correctness for them, who treat a hosted dashboard as the product, or who want compliance claims rather than bounded evidence boundaries. Assay is not a trust scoring engine, a general-purpose evaluation dashboard, or a hosted observability product.

V. Limitations and Boundaries A denial is fail-closed cautious behavior, not a determination of intent; an allow is a decision to forward, never proof that an action occurred. The consistency of declarations and observations is recorded alongside the decision result, never as a gate. Assay uses an explicit epistemology rather than a single security score: verified (direct evidence or offline verification), self-reported (no independent corroboration), inferred (bounded, documented rules), missing (no credible evidence), and does not output an aggregate trust score or safe/unsafe badge as its primary output. The historical fragmented IPI experimental results are dated 2026-03-02, commit 289a43ecc144; the report gives a p50 of 0.771 ms and a p95 of 1.913 ms for a deterministic set, measuring a complete local simulated tools/call round trip (including JSON-RPC transport and tool response), and does not represent policy decision overhead or current-version, end-to-end model performance. Assay-Runner is an internal/experimental measured-execution subsystem, positioned after the delegated Linux/eBPF acceptance path; its crate is included in the workspace release process for dependency resolution, but the release does not make Runner a standalone product, nor does it provide a separate stability commitment for its API.