Agent Receipt Validator MCP

A local stdio MCP server for validating signed agent execution receipts against evidence bundles.

This server wraps the verifiable-tool-invocation-flow Python package and exposes receipt validation as MCP tools for local clients such as Claude Desktop, Cursor, and other MCP-compatible agent runtimes.

Public package and related assets

• MCP server PyPI package: https://pypi.org/project/agent-receipt-validator-mcp/0.1.1/
• MCP server repository: https://github.com/joy7758/agent-receipt-validator-mcp
• Core receipt toolkit: https://github.com/joy7758/verifiable-tool-invocation-flow
• Core PyPI package: https://pypi.org/project/verifiable-tool-invocation-flow/0.1.1/
• GitHub Marketplace Action: https://github.com/marketplace/actions/verify-agent-execution-receipt
• Hugging Face validator demo: https://huggingface.co/spaces/joy7759/agent-receipt-validator

Documentation and agent-readable entry points

• Agent-readable index: llms.txt
• Software architecture: docs/software-architecture.md
• Reproducibility workflow: docs/reproducibility.md
• Release hygiene notes: docs/release-hygiene.md
• Basic usage walkthrough: examples/basic-usage.md
• Citation metadata: CITATION.cff

What This MCP Server Does

• Validates an execution_receipt.json payload against an evidence_bundle.json payload and a public key PEM.
• Generates fresh demo artifacts using the same deterministic demo flow as the core package.
• Summarizes verification reports into verdict, failed checks, warnings, and errors.
• Runs locally over stdio.

Installation From PyPI

pip install agent-receipt-validator-mcp==0.1.1

Installation From Local Checkout

cd agent-receipt-validator-mcp
python3.13 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"

MCP Client Config

Use this MCP client stdio configuration after installing the package in your local environment:

{
  "mcpServers": {
    "agent-receipt-validator": {
      "command": "agent-receipt-validator-mcp",
      "args": []
    }
  }
}

CLI Help Surface

The local command exposes a small help surface for checking the installed MCP server entrypoint:

agent-receipt-validator-mcp --help

The help output lists the stdio MCP server and the three exposed tools:

• validate_receipt_json
• generate_demo_artifacts
• summarize_verification_report

Tools

validate_receipt_json

Inputs:

• receipt_json: JSON string containing an execution receipt.
• evidence_bundle_json: JSON string containing the evidence bundle.
• public_key_pem: public key PEM string.
• audience: expected audience, default demo-validator.

Output:

{
  "verdict": "valid",
  "report": {
    "verdict": "valid"
  }
}

generate_demo_artifacts

Inputs:

• audience: expected audience, default demo-validator.

Output:

{
  "receipt_json": "{...}",
  "evidence_bundle_json": "{...}",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----...",
  "verification_report_json": "{...}",
  "verdict": "valid"
}

The demo artifacts are generated fresh at runtime. The server does not use static expired samples.

summarize_verification_report

Inputs:

• verification_report_json: JSON string containing a verification report.

Output:

{
  "verdict": "invalid",
  "failed_checks": ["tool_output_hash_match"],
  "warnings": [],
  "errors": ["tool_output_hash_mismatch"]
}

Boundary Statement

This MCP server validates signed execution evidence. It does not prove semantic correctness of the tool output. It does not prove that the policy itself is correct. It does not protect against a compromised signer. It does not replace sandboxing, IAM, access control, monitoring, or human approval. Do not pass private keys, API tokens, confidential evidence bundles, or production receipts to untrusted MCP clients.

This first release is a local stdio MCP server. Remote Streamable HTTP hosting and Smithery publication are future tasks.

Publishing

This package is intended to be published through PyPI Trusted Publishing using GitHub Actions OIDC.

Workflow:

• .github/workflows/publish.yml
• TestPyPI environment: testpypi
• PyPI environment: pypi

No PyPI API token is stored in this repository.

Trusted Publishing must be configured once in TestPyPI/PyPI before the workflow can publish.

Development

pytest tests/test_tools.py
agent-receipt-validator-mcp --help
python scripts/smoke_check.py