Irontrellis Evidence

io.github.zerohourzuluPublished by GitHub account zerohourzuluv1.0.0-rc.2Updated Oct 30, 2026

Local MCP server that copies selected files into an evidence packet while the agent holds authority

VerifiedSTDIODesktop onlyFiles & StorageSecurity & Monitoring

Overview

AI-generated overview

Local stdio MCP server that copies operator-selected files into a signed evidence packet only while the configured agent still holds authority in an…

What you can do
  • Collect evidence: copy the pre-selected files into a new packet under an operation id, if the agent's grant is still valid, and record the acknowledgment.
  • Reconcile retries: repeating the same operation id inspects the original attempt instead of copying again.
  • Report outcomes: replies distinguish recorded, reconciliation-only, unknown outcome, denied, refused and busy states, with a packet verification flag.
  • Refuse and log: a revoked grant yields a denial that the agent's own session records in the history.
When to use it
For teams using IronTrellis to keep a checkable record of who may act for whom, and who want an agent to assemble a bounded, verifiable evidence packet from files an operator chose in advance. It is a minimal reference boundary rather than a general file tool.
Requirements
Runs locally over stdio from the npm package @ramex-labs/irontrellis-mcp (install the next tag). Needs a gateway.json configuration file (mode 0600) naming the history file, domain, owner and controller, session, role and tenure, resource, input and output directories, a fixed selection, and a key file holding the session's private key. No environment variables or headers are declared.
Before you install
The tool writes files into the output directory and records entries in the history; it never deletes. The configuration holds a private key in keyFile, so keep the case directory private. The demo runs client and server under one user, so a client with the same filesystem access can bypass the tool; a real boundary needs separate OS identities. Records are signed with the agent's session key, not the owner key, so they stay unattested until the owner's next write. Packets prove which bytes…

Installation

In SourceWeft

  1. Open Irontrellis Evidence in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

IronTrellis Evidence MCP server

IronTrellis (formerly Continuity) keeps a checkable record of who may act for whom, and which duties survive when an AI agent is replaced.

irontrellis-evidence is a stdio MCP (Model Context Protocol) server with one tool, irontrellis_collect_evidence, that copies operator-selected files into a protected evidence packet if the configured agent still holds the authority in a format-2 IronTrellis history (format 2 is the history format this release writes). One operation id is one operation, so a retry reconciles the original attempt instead of copying again.

Need several approved tools, or tools the model may call repeatedly? Use @ramex-labs/irontrellis-mcp-gateway (exactly-once jobs and per-call mode). This package is the smallest complete example of the same boundary: your application chooses the agent, the source files, the destination and the key before launching the server; none of them is a tool argument. Concepts: docs/PRINCIPLES.md, docs/GLOSSARY.md.

This is 1.0.0-rc.2.3; install it from the next tag.

What happens, call by call

The quickstart below builds this case and runs its first two steps: an agent, bea, holds a grant to collect the evidence packet for incident:42, and one input file is selected.

StepWhat the server doesThe tool answers
bea asks for the packet, operation id example:collectionChecks bea's authority in the history, copies the selected file into a new packet and records the acknowledgmentRECORDED, packetVerified: true
bea repeats the same callInspects the original attempt; copies nothing; the history file is unchangedRECONCILIATION_ONLY
The owner revokes the grant, and bea asks again under a new idCopies nothing; bea's own session records the refusal in the history (code REVOKED)DENIED, reason: CORE_POLICY

60-second quickstart

sh
npm install -g @ramex-labs/irontrellis-mcp@next   # provides irontrellis-evidence (alias irontrellis-mcp), -setup and -demoirontrellis-evidence-setup /absolute/new-case     # synthetic input, disposable Ed25519 key, format-2 history, gateway.jsonirontrellis-evidence-demo /absolute/new-case/gateway.json

Expected: Tools: irontrellis_collect_evidence, then a RECORDED packet on the first call and RECONCILIATION_ONLY on the repeat, with packetVerified: true both times. To connect another MCP client, configure it to launch irontrellis-evidence --config /absolute/new-case/gateway.json (stdio).

Keep the case directory private; setup refuses to overwrite an existing directory. All three commands take --help and --version. A refusal (an existing target, a missing parent, a configuration that is missing, not 0600 or not valid) is one JSON line on stderr with exit code 2, {"status":"REFUSED","reason":<CODE>,"detail":<why>} (the server's own line names GATEWAY_CONFIGURATION_UNAVAILABLE as its reason and may add the underlying code), where detail names the file, field or limit at fault and never echoes configuration values or keys.

The tool

irontrellis_collect_evidence { operationId, resource }

ArgumentRule
operationIdA stable, application-owned id, 1–128 characters. Repeating it reconciles the original attempt.
resourceMust equal the configured resource; the schema pins it with an enum.

Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false. It creates files and never deletes any; repeating an id copies nothing.

ResultMeaningMCP tool error
RECORDEDAdmitted, copied, acknowledged in the history; acknowledgment is the recorded packet acknowledgment.no
RECONCILIATION_ONLYThe original attempt was inspected; nothing was copied. If that attempt's acknowledgment was never recorded, it may be recorded now; packetVerified and disposition say what the attempt achieved.no
OUTCOME_UNKNOWNAdmitted, but the copy or its acknowledgment is not confirmed (for example the selected input changed); packetVerified says whether the packet verified. Investigate; do not pick a new id.yes
DENIEDreason: CORE_POLICY (no current grant): the agent's own session records the refusal in the history, unless an identical refusal was recorded in the last minute or the agent's refusals pass six a minute; the reply's refusal says which (recorded: true with the eventId, or recorded: false with the reason). reason: ADDITIONAL_POLICY: an additional policy supplied by an embedding host refused the call or could not answer; the history records no refusal for it, and the policy's own audit holds the decision.yes
REFUSEDA bounded code: INVALID_ARGUMENTS, RUNTIME_NOT_CURRENT (retired or expired session), OPERATION_CONFLICT, CAPACITY_CONTROL_ONLY, … or GATEWAY_UNAVAILABLE.yes
BUSYOne collection at a time; repeat the same call.yes

An MCP tool error is a reply with isError: true. externalOutcome, which RECORDED, RECONCILIATION_ONLY and OUTCOME_UNKNOWN replies carry, is always NOT_PROVEN: a packet proves which selected bytes were copied, not that their contents are true.

Configuration

gateway.json (0600) has exactly these fields. Every choice is the operator's.

FieldWhat it holds
historyFileThe format-2 history
domainThe history's authorization domain
owner, controllerThe owner profile
sessionThe admitted runtime session
role, tenureThe agent's role and its current tenure
resourceThe one resource the tool acts on
inputDirectory, outputDirectoryWhere the selected files are read, and where packets are written
selectionFrom selectEvidence(inputDirectory); reopening never re-selects changed files
keyFileThe session's private key, 0x + 64 hex. The scheme is read from the session, and a key that is not the session's credential refuses startup.

The copy is bounded: at most 8 files, 64 KiB each, 256 KiB in total, into outputDirectory/<sha256(operationId)>/.

Embedding

createEvidenceServer(loadEvidenceTool(configFile, { additionalPolicy? })) returns an SDK Server (@modelcontextprotocol/server); serveEvidence(tool) serves it on stdio, to 2026-07-28 and 2025-era clients alike, behind a strict-JSON input guard (16 KiB frames, no duplicate keys, 5-second frame deadline, at most 1,024 messages in any 60 seconds). Input that breaks the guard never reaches the tool: the server stops with exit code 2.

The server refuses at startup rather than serving a configuration it cannot verify (GATEWAY_CONFIGURATION_UNAVAILABLE, exit 2). A legacy or format-1 history opens read only and the tool does not act on it; migrate it with irontrellis migrate.

Limits

LimitWhat it means for you
The demo runs client and server under one userA client with the same filesystem access can bypass the tool. A real boundary needs separate OS identities for the agent and the server, with the source, key, history and output directories reachable only by the server.
The server signs its records with the agent's session key, never the owner keyThose records stay unattested and unwitnessed until the owner's next write (docs/SECURITY.md).

Check it yourself

From a clone of the repository:

sh
pnpm installpnpm -r buildpnpm --filter @ramex-labs/irontrellis-mcp test

The tests drive the server over stdio, through a real MCP client and with raw frames: a retry, a revoked grant, a retired session, a replaced key, attempts to substitute the actor, paths or resource, duplicate keys, oversized or unfinished frames, and a message flood. They check this package as it ships. They do not test your deployment, and the limits stated above still apply.

Dependencies: @ramex-labs/irontrellis, @modelcontextprotocol/server and @modelcontextprotocol/client (2.2.0, pinned exactly). Apache-2.0.

Last reviewed: 24 October 2026. This page is revisited at each release.

Source: packages/mcp-evidence/README.md at commit cd34ad7

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the server did not start.

Version history

1
  1. v1.0.0-rc.2LatestOct 29, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts