phionyx-pipeline-mcp
This MCP server gates an AI agent's self-claims about its work against git diff truth and deterministic thresholds.
Verify completion claims ("fixed"/"done") via
phionyx_verify_claim— cross-checks paths, weights evidence type, returnspass | regenerate | rejectplus reasons.Cross-check claimed affected/tested paths against actual
git diffwithphionyx_verify_pathsto flag underreporting.Validate causal debugging chains (
phionyx_causal_trace) — requires ≥3 links and ≥40% code-specificity else returnsdeepen.Apply action-type-specific response gates (
phionyx_response_gate) before commits/deploys — strictest forclaim_fixedanddeploy; canblock,hedge, orrequire_toolfor unbound factual claims.Log lightweight snapshots (
phionyx_checkpoint) frequently to keep session telemetry dense.Produce end-of-session reports (
phionyx_session_report) with claims, directives, drift metrics, evidence taxonomy, and (if companion installed) signed audit chain head + validity.Optional P1/P2 enforcement:
require_toolfor external-state claims, continuity binding viaread_paths/referenced_sourcesto catch stale or unbound sources.
Verifies claimed code paths against actual git diff to ensure agent's declarations match repository truth.
Provides a command-line gate helper that can be used in pre-commit hooks to reject or require regeneration of claims before commits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@phionyx-pipeline-mcp Verify my claim: I fixed the auth timeout bug and tested login and logout paths."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
phionyx-pipeline-mcp
A self-governance MCP server for Claude Code — gates the agent's own "I fixed this / I tested that / this code path changed" declarations against
git difftruth and a deterministic gate.
phionyx-pipeline-mcp solves a less-discussed agent-trust problem: when an AI coding agent reports back on its own work, that report is itself a trust object. Without verification, you accept it on faith.
This package gives any MCP-capable host (Claude Desktop, Cursor, Zed, VS Code, JetBrains) a six-tool surface that turns those self-reports into reviewable evidence — coverage of paths claimed vs. paths actually touched, severity-weighted evidence taxonomy, drift tracking across a session, and an explicit pass | regenerate | reject directive before the agent claims "done."
Where this sits in the Phionyx stack
Phionyx ships three distinct things, each with its own version line. This package is the gate:
Engine —
phionyx-core(current release on PyPI): the deterministic runtime (46-block canonical pipeline, state vector, kill switch, HITL, ethics/safety gates, audit-record contracts — the signed chain is demonstrated at the MCP boundary today).Gate —
phionyx-pipeline-mcp(this package): the inward-facing self-claim gate described here. It verifies what the agent says about its own work againstgit difftruth and a deterministic gate. v0.3.1 adds opt-in, default-off evidence binding (therequire_tooldirective + continuity binding) on top of the claim-grounding gate. It is the claim-governance layer of the Phionyx governance stack;phionyx-mcp-server(current release on PyPI) is the outward MCP trust boundary.Format — the AI Runtime Evidence Protocol (AIREP): an experimental, vendor-neutral open format for an AI decision receipt — one signed, hash-chained, offline-checkable record per AI runtime decision, readable by anyone and tied to no vendor. Phionyx's Reasoned Governance Envelope (RGE) is developed alongside AIREP; a conformant projection between the two is not implemented (measured 2026-08-06: AIREP's own reference verifier rejects an RGE envelope handed to it directly). AIREP is a proposed format, not a ratified standard. AIREP v0.2.0-beta.1 was published on 9 September 2026 as an experimental prerelease: it ships a first-party Python producer for Decision, Control, Execution and Effect artifacts, runnable lifecycle examples and structured reconciliation; the v0.1 line remains frozen and supported. External implementation results are version- and role-specific — an independently authored producer measured against frozen v0.1.2, and an independently implemented consumer/verifier measured against an earlier v0.2 handoff — and they do not establish same-beta producer-to-consumer interoperability. See
ai-runtime-evidence-protocol.
These three version lines — engine v0.9.1, gate v0.3.1, and AIREP v0.2.0-beta.1 (experimental prerelease; v0.1 frozen and supported) — are never cross-attributed.
Related MCP server: did-it
How it works — three-stage verification
Stage 1: LLM declaration → Stage 2: Repo truth → Stage 3: Deterministic gate
"I fixed X, tested Y, git diff parsed; functions evidence + recency + revision
affected paths a,b,c" extracted; cross-checked thresholds → directiveThe gate is deterministic. Stage 1 (the agent's input) is stochastic. Stage 2 — verifying the agent's path declarations against the actual git diff — is what narrows the gap.
(These three stages are internal to the gate's verification flow. They are unrelated to the broader Phionyx governance-stack layers.)
Where this fits on phionyx.ai
This package surfaces under phionyx.ai/bounded-authority — the safety-first AI providers entry. It is the inward-facing self-claim gate that verifies the agent's own "I fixed / I tested / this code path changed" narration against the repository's actual diff and a deterministic gate, producing a pass | regenerate | reject directive paired with reviewer-runnable evidence.
Companion package: phionyx-mcp-server
This package is the inward-facing layer: it gates what the agent says about its own work.
A companion package, phionyx-mcp-server (current release on PyPI), is the outward-facing layer: it sees the host calling a third-party MCP server and signs evidence of that call (descriptor hash, drift detection, audit chain).
When both packages are installed and registered with the same Claude Code host, they agree on a single trace_id per session via PHIONYX_TRACE_ID (with ~/.phionyx/active_trace file fallback). One conversation = one trace = a joined view of the third-party tool calls and agent self-claim gate decisions recorded in that session.
phionyx_session_report (this package) surfaces the server-MCP envelope chain head + validity inline, so a reviewer can see both layers in one JSON.
Install
# This package only:
pip install phionyx-pipeline-mcp
# With the outward-facing companion (recommended for full session evidence):
pip install "phionyx-pipeline-mcp[mcp-server-integration]"Register with Claude Code
Add to .claude/mcp.json in your project:
{
"mcpServers": {
"phionyx-pipeline": {
"command": "phionyx-pipeline-mcp"
},
"phionyx-mcp-server": {
"command": "phionyx-mcp-server"
}
}
}Both servers will share ~/.phionyx/active_trace by default.
Tool surface
Tool | When to call |
| Before claiming "fixed" or "done." Takes the claim, the evidence, the evidence type, paths tested, paths affected. Returns a directive ( |
| While debugging. Validates a causal chain from symptom to root cause. Chains shorter than 3 links or weaker than 40% code-specificity get a |
| Before committing or deploying. Action-type-specific thresholds: |
| Cross-check claimed-affected and claimed-tested paths against |
| Lightweight snapshot — call frequently to keep the session telemetry dense. |
| End-of-session summary: claims, directives, drift metrics, evidence taxonomy, and (if the server MCP is installed) the audit chain head + validity. |
Reviewer-runnable CLI (phionyx)
pip install phionyx-pipeline-mcp also installs a phionyx command that exposes the same three-stage verification as the MCP server, but reachable from a plain terminal — no Claude Code / MCP host required.
Four subcommands:
# 1. Verify a self-claim against the gate
phionyx verify-claim \
--claim "scenario continuation bug is fixed" \
--evidence "12 scenes played, quest_complete=True" \
--type integration_test \
--tested "src/foo/regression.py::regression_handler" \
--affected "src/foo/regression.py"
# 2. Aggregate the audit chain over the last N days
phionyx audit --days 30
phionyx audit --days 7 --json # machine-readable
# 3. Replay a specific session's timeline by trace_id (or unique prefix)
phionyx replay --trace <trace_id_or_session_id_prefix>
# 4. The killer demo — reviewer reproduces the failure mode in 5 seconds
phionyx demo broken-test-disabledThe demo is the entry point a reviewer should try first. It runs a scripted scenario in which Claude claims a fix passes and the gate detects that no tested-path coverage exists and the evidence weight is the bottom of the taxonomy — and rejects the claim. The exit code is 2 because the gate did its job.
Exit codes:
Code | Meaning |
|
|
|
|
|
|
| error (invalid args, missing telemetry, internal failure) |
CLI and MCP-host invocations write to the same telemetry directory (PHIONYX_PROJECT_ROOT/data/mcp_telemetry/), so phionyx audit and phionyx replay see prior sessions started inside Claude Code or any other MCP-capable host.
Evidence taxonomy
Not all evidence is equal. The gate weights confidence by the type of test that backs a claim:
Evidence type | Weight |
| 0.9 |
| 0.8 |
| 0.7 |
| 0.6 |
| 0.5 |
| 0.4 |
| 0.3 |
| 0.0 |
A claim_fixed action with evidence_type=none will be rejected outright; even high confidence values cannot compensate for missing test evidence.
Pre-commit gate helper
A standalone phionyx-pipeline-check-gate CLI reads the recent telemetry and exits non-zero if the most recent gate directive was reject or regenerate. Drop it into your pre-commit hook to enforce the discipline:
phionyx-pipeline-check-gate --mode pre-commitExit codes: 0 pass · 1 failed (recent reject/regenerate) · 2 no telemetry (warn-only).
Shared-trace contract
When phionyx-mcp-server is also installed, this package extends phionyx_session_report's output with:
{
"trace_id": "<active trace>",
"mcp_envelope_chain": {
"trace_id": "<same trace>",
"count": 7,
"head_hash": "sha256:...",
"valid": true,
"broken_at": null
}
}The integration is read-only — this package imports FilesystemEnvelopeStore + verify_chain from phionyx-mcp-server and reads its chain. No cross-package write coupling. When the server package isn't installed, the field reports "phionyx-mcp-server not installed" and the rest of the report continues to work.
Tests
pip install -e ".[test]"
pytest tests/ -qLicense
AGPL-3.0-or-later. See LICENSE.
See also
phionyx.ai/bounded-authority — entry pillar this package surfaces under
phionyx.ai/evidence — Evidence Matrix: every load-bearing claim paired with a reviewer-runnable command
ai-runtime-evidence-protocol— AIREP, the experimental vendor-neutral open format for per-decision AI decision receipts (signed, hash-chained, offline-checkable). Phionyx's Reasoned Governance Envelope is its developed alongside AIREP; a conformant projection between the two is not implemented (measured 2026-08-06: AIREP's own reference verifier rejects an RGE envelope handed to it directly). A proposed format, not a ratified standard.Project hub: github.com/halvrenofviryel/phionyx-research
Engine (PyPI):
phionyx-core— the deterministic runtime (current release on PyPI)Outward MCP layer:
phionyx-mcp-server— trust boundary over third-party MCP tool callsInspect AI bridge:
phionyx-eval-inspect— envelope chain →.evallogFramework adapters (alpha):
phionyx-langchain-langgraph·phionyx-openai-agents
MCP compatibility (0.3.2 candidate)
This entry point uses mcp.server.fastmcp from MCP 1.x. Installation is now
bounded to mcp>=1.27.0,<2; MCP 2.x is not supported by this entry point.
The upper bound prevents a successful dependency install followed by a startup
import failure. It does not claim compatibility with every future MCP 1.x release.
Available Tools
6 toolsphionyx_causal_traceB
Validate a causal debugging chain. Call when investigating a bug.
Args: symptom: What the user observes (e.g. "scenarios end at scene 2") causal_chain: Arrow-separated chain from symptom to root cause (e.g. "0 choices shown → play page reads res.choices → play_card returns empty → make_choice uses wrong key")
Inputs: symptom (required), causal_chain (required). Returns: object
phionyx_checkpointA
Lightweight physics state snapshot. Call frequently — after completing any subtask, before switching context, or when reporting progress.
This is cheap (no git diff, no verification). Use it to keep the telemetry timeline dense so the founder can track session physics in real time.
Args: context: Brief note of what you're doing (e.g. "finished implementing selector")
Inputs: context. Returns: object
phionyx_response_gateA
Response revision gate with action-type-specific thresholds. Call before committing.
Directives: pass | hedge | regenerate | block | require_tool (P1). Different action types trigger different threshold profiles:
claim_fixed: strictest (entropy_reject=0.90, phi_min=0.08)
deploy: very strict (entropy_reject=0.85, phi_min=0.10)
default: standard pipeline thresholds
require_tool (P1): for factual action_types (claim_fixed/claim_working/deploy) with no externally-bound evidence, the result carries require_tool{triggered}; with PHIONYX_GATE_REQUIRE_TOOL_ENFORCE=1 an otherwise-passing directive becomes 'require_tool' — bind real evidence (run a tool) before the claim can pass.
continuity_binding (P2): the result carries continuity_binding{bound,stale,dds} from the session constraint ledger. compute_dds(confidence, continuity_score) flags "confident while binding unbound/stale"; with PHIONYX_GATE_CONTINUITY_ENFORCE=1 an otherwise-passing directive is downgraded to 'hedge' (re-bind constraints).
ask_question / make_claim (Block 15 short-circuit): each identifier in
artifact_referencesis scored against the read-knowledge boundary by phionyx_core's KnowledgeBoundaryDetector; any source not present inartifact_paths_readis assessed outside the boundary → directive='regenerate' with the ungrounded set + the core's reasoning surfaced. Use 'ask_question' BEFORE asking about a named artifact; use 'make_claim' BEFORE asserting what a named source (file, paper, theory, config) says/contains.
Args: action_type: claim_fixed | claim_working | deploy | refactor | investigate | ask_question | make_claim confidence: Your confidence 0.0-1.0 evidence_count: Number of independent test/verification points evidence_type: Type of evidence (see phionyx_verify_claim for options) affects_user_facing: Whether this change is visible to end users artifact_references: Comma-separated artifact identifiers mentioned in the question/claim (file paths, URLs, issue numbers, named sources). Only meaningful when action_type in {'ask_question', 'make_claim'}. artifact_paths_read: Comma-separated artifact identifiers actually opened this turn (Read tool results, gh issue view output, WebFetch URLs). Only meaningful when action_type in {'ask_question', 'make_claim'}.
Inputs: confidence (required), action_type (required), evidence_count (required), evidence_type, +3 more. Returns: object
phionyx_session_reportA
Session summary: claims, directives, drift metrics, evidence taxonomy, physics state.
Inputs: no named parameters. Returns: object
phionyx_verify_claimA
Verify a completion claim using three-layer verification. Call BEFORE saying 'fixed' or 'done'.
Layer 1: Parse your declarations (claim, evidence, paths) Layer 2: Cross-check paths against git diff (input verification) Layer 3: Physics gate (phi + entropy + revision thresholds)
P1 require_tool: if the claim asserts a factual / external-state fact (live / deployed / version / merged / tests-pass / endpoint-up) and the evidence is not externally bound (only code_review/none, not a run/inspection), the result carries require_tool{triggered,...}; with PHIONYX_GATE_REQUIRE_TOOL_ENFORCE=1 an otherwise- passing directive becomes 'require_tool' — go bind the evidence (run the tool) first.
Args: claim: What you're claiming (e.g. "scenario continuation bug is fixed") evidence: What test output proves it (e.g. "12 scenes played, quest_complete=True") evidence_type: Type of evidence — determines confidence weight. One of: browser_test, manual_repro, integration_test, endpoint_test, log_inspection, unit_test, code_review, none code_paths_tested: Comma-separated functions/endpoints you actually tested code_paths_affected: Comma-separated functions/endpoints affected by the change referenced_sources: (P2b) Comma-separated sources the claim cites/depends on (roadmap, spec, a module/file). Optional. read_paths: (P2b) Comma-separated sources actually Read/bound THIS turn. Optional — when BOTH this and referenced_sources are given, the gate checks read_but_not_bound (a cited source not bound this turn → continuity violation; with PHIONYX_GATE_CONTINUITY_ENFORCE=1 → 'regenerate'). Omit (leave null) when no read-set is available → check is skipped (non-regressive).
Inputs: claim (required), evidence (required), evidence_type (required), code_paths_tested (required), +3 more. Returns: object
phionyx_verify_pathsA
Cross-check your claimed code paths against git diff reality. Call to verify your own declarations.
Compares what you say you affected/tested against what git diff actually shows. Returns discrepancies, trust score, and warnings about underreporting.
Args: claimed_affected: Comma-separated paths you claim are affected claimed_tested: Comma-separated paths you claim to have tested
Inputs: claimed_tested (required), claimed_affected (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tools have distinct purposes, though response_gate and verify_claim share some verification concepts. Detailed descriptions help differentiate them.
All tools start with 'phionyx_' and use snake_case. Despite some being nouns and others verb-noun, the pattern is consistent.
Six tools is an appropriate number for a pipeline validation server, covering key operations without being excessive.
The set covers causal debugging, state snapshots, gates, verification, and reporting. Minor gaps like explicit rollback may exist, but core workflows are supported.
Maintenance
Related MCP Connectors
Git-native policy layer for AI agents: check_action verdicts against rules approved via PR.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Verifies AI agent work end to end: real artifacts and outcomes checked, not self-reported success.
Verify what your AI coding agent built: test coverage, recorded browser tests, a done verdict.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables acceptance gates for AI coding-agent runs by recording evidence, running deterministic validation, applying a quality gate, and rendering auditable outcomes.7Apache 2.0
- AlicenseAqualityCmaintenanceAudits coding agents' claimed actions against the actual Git working tree, blocking completion if any claimed changes are unverified.2MIT
- AlicenseAqualityCmaintenanceEnables AI coding agents to submit work for external review before declaring a task done, receiving evidence-backed fix lists and verdicts based on git-measured changes and calibrated quality scoring.3MIT
- AlicenseAqualityBmaintenanceEnables Claude to independently check an AI agent's work in a local git repository by recording a baseline, running only the checks relevant to the changed files, and cross-checking what the agent claimed. Returns a compact, evidence-labelled report with a verdict and a ready-to-paste next prompt, so unverified success claims can't slip through.8MIT