RealityFirst MCP
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., "@RealityFirst MCP I wrote compact_summary.json; verify the claim before I report success."
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.
RealityFirst MCP
A small MCP behavior layer for coding agents that should verify reality instead of trusting their own completion claims.
It does not replace your filesystem, terminal, GitHub, browser, deployment, or machine-control tools. It sits beside them and gives the agent a reusable discipline:
Use tools for facts. Use the model for decisions. Reality beats the report.
Why
Coding agents are often good at doing work and surprisingly bad at proving that they actually did it.
A typical failure looks like:
agent: "I wrote compact_summary.json"
disk: "compact_summary placeholder"RealityFirst turns completion claims into explicit evidence gates.
wrote/created-> read the exact target backdeleted-> prove exact absencebuilt-> terminal receipt + artifact checktests passed-> test/terminal receiptdeployed/restarted-> fresh runtime probeUNKNOWN_DO_NOT_REPLAY-> reconcile the same lineage before any replay
Related MCP server: Recommend Agentic Trust Layer
Core invariants
REALITY > CLAIM
READ WIDE, LOAD NARROW
FILE EXISTS != ACTIVE
HISTORY != CURRENT
fresh live Reality
> CURRENT law
> latest cutover
> active implementation/tests
> history
> model report
CREATED / WRITTEN / BUILT / DEPLOYED / PASSED / UPDATED / DELETED / SYNCED
=> independent readback / receipt / runtime proof
UNKNOWN SIDE EFFECT
=> NO BLIND REPLAY
REPLACE
=> PROVE -> CUTOVER -> RETIRE OLDWhat it exposes
Tools
classify_claim— classify a claim and return its evidence gatebuild_verification_plan— suggest the smallest independent verification plancheck_completion_evidence— PASS/FAIL/UNKNOWN for supplied evidence; labels are structurally validatedvalidate_evidence— reject fake hash/stat/readback labels that lack real payload structureresolve_precedence— resolve current-vs-history conflictscheck_replay_safety— block blind replay on unresolved side effectscompact_evidence— keep decisive evidence without losing source refsrecord_loss— create a structured anti-repeat/loss-ledger entry
Resources
realityfirst://policy/corerealityfirst://policy/completionrealityfirst://policy/precedence
Prompts
reality_firstread_widecrosscheck_completion
Install and run
Requires Python 3.10+ and an MCP host.
Using uvx directly from GitHub:
uvx --from git+https://github.com/zone5101/realityfirst-mcp realityfirst-mcpOr clone it:
git clone https://github.com/zone5101/realityfirst-mcp
cd realityfirst-mcp
uv sync
uv run realityfirst-mcpThe server uses stdio by default.
The current official MCP Python SDK 2.x is used (mcp>=2,<3).
MCP host config
Generic stdio configuration:
{
"mcpServers": {
"realityfirst": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/zone5101/realityfirst-mcp",
"realityfirst-mcp"
]
}
}
}For Cline, add that server in its MCP server configuration. Other MCP hosts use the same command/args shape even if the surrounding configuration file differs.
Suggested agent instruction
Adding the MCP server is useful; telling the agent when to call it makes it much more effective:
Use RealityFirst whenever you are about to trust or emit a completion/current-state claim.
Before saying created/written/built/deployed/passed/updated/deleted/synced:
1. classify the claim,
2. obtain independent evidence with the real filesystem/terminal/runtime tool,
3. call check_completion_evidence,
4. only claim completion on PASS.
For architecture/current-state questions, resolve conflicts with:
live Reality > CURRENT law > latest cutover > active implementation/tests > history.
Never blindly replay UNKNOWN_DO_NOT_REPLAY or unresolved side effects.Example: catching a fake completion
# The agent says it wrote a file.
classify_claim("compact_summary.json was written")
# -> claim_type: file_written
# -> requires readback
# If all we have is the agent's own report:
check_completion_evidence(
claim_type="file_written",
evidence=[{"type": "model_report", "valid": True}]
)
# -> FAIL
# After the real filesystem tool reads the target:
check_completion_evidence(
claim_type="file_written",
evidence=[{"type": "readback", "valid": True, "ref": "file://compact_summary.json"}]
)
# -> PASSDesign boundary
RealityFirst is deliberately not another execution engine.
Agent
├── filesystem / terminal / GitHub / LivingOS / cloud tools
└── RealityFirst MCP
├── classify the claim
├── define required proof
├── resolve precedence
└── reject unsupported completionThe authoritative side effect still belongs to the tool that owns it.
RealityFirst should never become a second mutation authority.
Development
uv sync --extra dev
uv run pytest -qTest case zero is the failure that motivated the project: an agent reports that output files were written while disk reality still contains placeholders.
Status
0.1.1 — alpha.
The first release intentionally stays small: claim classification, evidence gates, current-state precedence, replay safety, compaction, and reusable MCP prompts/resources.
License
MIT
Available Tools
8 toolsbuild_verification_planC
Build a minimal Reality-first verification plan without executing external tools.
Inputs: claim (required), claim_type (required), available_tools. Returns: object
check_completion_evidenceC
Check whether a completion/current-state claim has enough independent evidence.
Inputs: evidence (required), claim_type (required). Returns: object
check_replay_safetyC
Block blind replay when side effects or request lineage are unresolved.
Inputs: state (required), side_effect_state. Returns: object
classify_claimC
Classify an agent claim and return the evidence gate it must satisfy.
Inputs: claim (required), claim_type. Returns: object
compact_evidenceC
Compact evidence while retaining source refs and prioritizing direct Reality proof.
Inputs: evidence (required), max_items. Returns: object
record_lossB
Create a structured loss-ledger entry. This tool does not persist it.
Inputs: claim (required), why_wrong (required), evidence_refs (required), corrected_form (required), +1 more. Returns: object
resolve_precedenceC
Resolve conflicting claims using Reality > CURRENT law > cutover > implementation/tests > history.
Inputs: candidates (required). Returns: object
validate_evidenceC
Validate evidence payload structure before it can satisfy a completion gate.
Inputs: evidence (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 8 tools
Most tools have clearly distinct purposes (classify vs resolve vs compact). However, validate_evidence, check_completion_evidence, and check_replay_safety all perform gate-style checks on evidence, which could cause confusion without careful reading of descriptions.
All tool names follow a consistent snake_case verb_noun pattern (validate_evidence, resolve_precedence, check_replay_safety, etc.). There are no mixed conventions or vague verbs.
With 8 tools, the set is well-scoped for a verification/evidence-gate server. Each tool addresses a distinct step in the workflow, and there is no excessive proliferation.
The surface covers validation, classification, conflict resolution, planning, and loss recording, but record_loss explicitly does not persist entries, leaving no way to actually store or retrieve loss data. There is also no tool to execute verification or persist evidence, creating dead ends for some workflows.
Maintenance
Related MCP Connectors
One-stop claim verification for AI agents: verdicts with confidence, evidence, signed receipts.
Source control for coding agents: declare an intent, settle overlaps before code, verify each push.
Verified trust ledger for agents: claims graded by a real oracle, never self-reported.
Preflight, approve, and prove consequential agent actions with signed evidence and x402 tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancePrevents autonomous agents from fabricating tool results by verifying HMAC-signed receipts against epistemic claim types, forcing re-grounding or escalation before actions commit.MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to verify claims with evidence-based truth scores and confidence levels by running a deterministic pipeline of evidence lanes and adversarial checks.26MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to classify every claim into evidence tiers (FACT/INFERENCE/SPECULATION/UNVERIFIED) with attached evidence, forcing deterministic, evidence-gated reporting without LLM or network calls.25 PyPIMIT
- FlicenseAqualityBmaintenanceEnables agents to verify claims against a real falsification ledger, querying pre-registered refutation thresholds, recorded verdicts, and verifier drift metrics instead of guessing.5-