Matrix Scroll

Signed machine-action records with offline verification for MCP, Git, and CI.

An MCP server can change its tool descriptions or input schemas after installation. A Git commit can also declare an actor or tool without carrying a signed authorization record. Matrix Scroll records both surfaces as Ed25519-signed evidence that reviewers can verify offline.

The matrixscroll-mcp stdio server exposes 14 tools for commit envelopes, action records, pull-request checks, Git notes, MCP surface manifests, agent traces, and the SSX360 USB signer. Local signing and verification need no cloud account.

SSX360 has completed and produced the USB signer shown below. SSX360 supplies it by direct inquiry through SSX360 contact or mission@ssx360.com. Integration details are available to qualified operators during setup.

Matrix Scroll is an open protocol. The Python SDK is Apache-2.0 software, and the specification and vectors are CC0 1.0.

Contents

• Install the MCP server
• MCP tools
• Detect MCP tool-surface changes
• Use the SSX360 USB signer
• Sign and verify from the CLI
• Verification boundaries
• Verify the release
• Security and license

Install the MCP server

Install the current release from PyPI:

pip install "matrixscroll[mcp]==0.7.0"

Register the stdio server in your MCP client:

{
"mcpServers": {
"matrixscroll": {
"command": "matrixscroll-mcp",
"args": []
}
}
}

On Windows, use the full path to matrixscroll-mcp.exe inside the active virtual environment if the command is not on PATH.

Start the executable directly when you want to inspect the server over stdio:

matrixscroll-mcp

After your client connects, call status. The server reports the local identity, hook state, and envelope count.

MCP tools

The 0.7.0 server exposes these tools:

Tool	What it does	Network or write behavior
status	Reports local identity, hook state, and envelope count	Read-only and local
create_envelope	Creates an Ed25519-signed Git commit envelope	Writes a local envelope by default
verify_envelope	Verifies one signed envelope and its policy fields	Read-only and local
sign_action	Signs provenance for CI, infrastructure changes, migrations, API calls, or other actions	Writes only when save_path is set
verify_pr_range	Checks every commit in a Git range	Local for local, notes, or bundle. Hosted mode requires an API key
publish_notes	Publishes local envelopes to refs/notes/matrixscroll	Writes local Git notes
audit_export	Exports evidence for review	Writes a local bundle or uses the hosted API when configured
list_envelopes	Lists organization envelopes	Requires SSX360_API_KEY and the hosted API
connect_card	Probes the SSX360 USB signer over USB CDC	Opens the configured serial port
scan_mcp_server	Fingerprints MCP tool names, descriptions, and input schemas	Read-only when tools are supplied
sign_mcp_manifest	Signs an MCP tool-surface manifest	Writes only when save_path is set
verify_mcp_manifest	Verifies a manifest and compares it with a signed baseline	Read-only and local
sign_agent_trace	Signs a browser-agent JSONL trace	Writes a signed envelope
verify_agent_trace	Verifies a signed trace and optionally checks the source bytes	Read-only and local

An API key is optional. Local signing, offline verification, MCP manifest checks, and USB signer access do not require one. Hosted organization history and hosted range verification use SSX360_API_KEY.

Detect MCP tool-surface changes

Matrix Scroll records an MCP server's tool names, descriptions, and input schemas in a signed manifest. Re-scan the server after an update and compare it with the install-time baseline.

pip install "matrixscroll[mcp]==0.7.0"
matrixscroll mcp scan \
--connect stdio \
--server-command "npx -y some-mcp-server" \
--output manifest.json \
--pretty
matrixscroll mcp sign manifest.json \
--output baseline.signed.json
matrixscroll mcp scan \
--connect stdio \
--server-command "npx -y some-mcp-server" \
--output current.json
matrixscroll mcp sign current.json \
--output current.signed.json
matrixscroll mcp verify current.signed.json \
--baseline baseline.signed.json \
--pretty

The verify command exits with code 2 when the signature is invalid or the current tool surface differs from the signed baseline. You can also scan an exported tools/list response without starting a server:

matrixscroll mcp scan --tools tools.json --output manifest.json --pretty

Use the SSX360 USB signer

Product visualization of the finished SSX360 USB signer. Supplied configurations can vary in enclosure details. The product documentation supplied with each unit names that configuration's signing boundary.

Install the hardware and MCP extras:

pip install "matrixscroll[mcp,hardware]==0.7.0"

Set the hardware provider and USB CDC port before starting the MCP server.

Windows PowerShell:

$env:MATRIXSCROLL_MODE="hardware"$env:MATRIXSCROLL_SE050_PORT="COM3"
matrixscroll status
matrixscroll-mcp

Linux:

export MATRIXSCROLL_MODE=hardware
export MATRIXSCROLL_SE050_PORT=/dev/ttyACM0
matrixscroll status
matrixscroll-mcp

You can also pass the hardware settings through the MCP client configuration:

{
"mcpServers": {
"matrixscroll": {
"command": "matrixscroll-mcp",
"args": [],
"env": {
"MATRIXSCROLL_MODE": "hardware",
"MATRIXSCROLL_SE050_PORT": "COM3"
}
}
}
}

Call connect_card to confirm that the signer responds. Then call status to inspect the active provider before creating an envelope.

SSX360 supplies the finished signer through direct contact. Ask for the Matrix Scroll USB signer through SSX360 contact. The hardware is not distributed through PyPI or listed for self-service purchase.

How hardware signing works

1. The signer creates and retains the private Ed25519 key in hardware.
2. The host sends canonical record bytes and receives the public key and detached signature.
3. Matrix Scroll assembles the record and checks it with the same offline verifier used for software signing.

The host receives only the public material needed to verify the record. Qualified operators receive the integration guide during setup.

Sign and verify from the CLI

The Python package includes a CLI and Git hooks for workflows that do not use MCP.

pip install "matrixscroll==0.7.0"
matrixscroll hook-install
export MATRIXSCROLL_ACTOR_TYPE=ci
export MATRIXSCROLL_TOOL=release-runner
git commit -m "feat: automate release"
matrixscroll envelope-verify "$(git rev-parse HEAD)"

Sign a JSON manifest directly:

matrixscroll sign release.json > release.signed.json
matrixscroll verify release.signed.json

matrixscroll verify exits with code 0 for a valid signature and code 2 for invalid input, a failed signature, a mismatched device identity, or an unsupported schema or algorithm.

Verification boundaries

• Release: PyPI matrixscroll==0.7.0 installs the 14-tool stdio MCP server and Git hooks. The release also includes the MCP Trust Scanner, offline verification, and USB signer host integration.
• Hardware supply: SSX360 produces the USB signer and supplies it after a direct inquiry. PyPI distributes the host software.
• Hosted tools: list_envelopes and the hosted modes of verify_pr_range and audit_export require SSX360_API_KEY and a deployed SSX360 API. Local signing and verification remain available without a key.
• Post-quantum evaluation path: the optional matrixscroll[pqc] extra provides ML-DSA and SLH-DSA through liboqs. This module has no CMVP validation. liboqs states that applications should not rely on it to protect sensitive data in production.
• Verification scope: an Ed25519 signature proves that the signed bytes match and correspond to the included public key. A trusted-key and authorization policy establishes whether the declared actor_type can perform the action.
• Adjacent controls: identity and access management, sandboxing, prompt filtering, and agent runtime policy remain separate controls.

Verify the release

GitHub Actions publishes each Matrix Scroll release through PyPI Trusted Publishing. PyPI records a PEP 740 attestation for the wheel and source distribution.

Ask PyPI for the 0.7.0 wheel provenance:

curl -H "Accept: application/vnd.pypi.integrity.v1+json" \
https://pypi.org/integrity/matrixscroll/0.7.0/matrixscroll-0.7.0-py3-none-any.whl/provenance

The response names the GitHub publisher:

{
"kind": "GitHub",
"repository": "SSX360/matrixscroll",
"workflow": "publish.yml",
"environment": "pypi"
}

Compare the attested subject[].digest.sha256 value with the SHA-256 digest of the file you downloaded. Stop if the repository, workflow, or digest differs.

Security and license

Read the security policy and security properties. Report vulnerabilities privately to security@matrixscroll.com or through a GitHub Security Advisory.

Matrix Scroll code is licensed under Apache-2.0. SPEC.md and vectors/ are released under CC0 1.0.

Resource	Link
Documentation	matrixscroll.com/docs
MCP Trust Scanner	matrixscroll.com/scan
Offline verifier	matrixscroll.com/verify
Protocol specification	matrixscroll.com/spec
Source repository	github.com/SSX360/matrixscroll
SSX360 contact	Contact SSX360