T-Rex MCP projection

The authorization and receipt contract for a future agent-triggered change-preview verifier.

T-Rex MCP projection

This document fixes the architecture for exposing the direct T-Rex change-preview workflow to an MCP client. It is a design contract, not a claim that the execution tool ships today.

The current codevetter-mcp server remains a strictly read-only history and graph interface. It does not run T-Rex, launch a browser, or write a verification receipt.

Why the boundary is separate

The three existing product paths do not have identical authority:

Calling the current MCP server “read-only” while adding a tool that launches a browser and persists a receipt would make its contract misleading. A future verification projection therefore uses a separate process and permission.

Process identity

The planned binary is codevetter-verify-mcp. It will not replace or extend codevetter-mcp.

Starting the process will require an owner-controlled, explicit verification enablement for one repository. Enabling history MCP access alone will never authorize verification execution.

The process receives one canonical repository scope at startup. The tool does not accept arbitrary repository paths, clone repositories, or switch scope between calls.

Tool contract

The first tool is planned as:

verify_change_preview

Its closed input shape is:

{
  "source": {
    "kind": "pull_request",
    "value": "https://github.com/acme/widget/pull/42"
  },
  "preview_url": "https://widget-pr-42.example.com"
}

source.kind is exactly pull_request or range. The value is exactly one canonical PR URL or bounded two-dot/three-dot Git range. preview_url is one credential-free HTTP(S) URL.

The tool does not accept:

• a repository path;
• a shell command, test command, or dependency installer;
• cookies, credentials, headers, or browser storage;
• a model, prompt, route, click plan, or mutation request;
• a second source or preview.

Shared execution authority

The MCP adapter will call the same execute_trex_preview service used by Tauri and the CLI. It must not reimplement source resolution, preview identity, route selection, browser execution, aggregation, persistence, or verdicts.

The shared service retains the current guarantees:

• source resolution is exact, bounded, shell-free, and checkout-read-only;
• preview identity is verified, claimed, or mismatched from headers;
• routes are deterministic and bounded;
• browser work is unauthenticated navigation and observation only;
• no model chooses actions or verdicts;
• the canonical receipt remains authoritative.

Output contract

A completed tool call returns the versioned TrexPreviewReceipt without an MCP-specific verdict overlay. The receipt preserves:

• exact base/head identities and changed paths;
• preview URL and identity evidence;
• selected routes and reasons;
• journey evidence and artifacts;
• limitations, duration, and run time;
• passed_with_limits, failed, or no_confidence.

Invalid input, preview mismatch, incomplete evidence, persistence failure, and cleanup failure remain no_confidence. The MCP adapter must not translate an operationally incomplete run into a successful result because the protocol call itself completed.

Protocol/framing errors may use MCP errors. Verification outcomes must use the canonical receipt shape so CLI, desktop, and MCP consumers do not diverge.

Write boundary

T-Rex is read-only toward the target repository and preview. It does write one local canonical receipt to CodeVetter’s application data.

The future settings copy and MCP tool metadata must say “local verification execution,” not simply “read-only.” The process will record bounded access metadata without prompt, profile, credential, or page content.

Authorization lifecycle

Before implementation, the feature must define:

1. a separate per-repository verification enablement;
2. how a client discovers and launches the dedicated binary;
3. how enablement is revoked while a process is running;
4. bounded concurrent-run ownership and cancellation;
5. receipt/audit retention;
6. protocol and end-to-end tests proving the history MCP cannot execute it.

No verification MCP binary should be bundled until those lifecycle behaviors are implemented and qualified.

Explicit exclusions

The projection does not authorize:

• authenticated or state-mutating journeys;
• repository cloning or dependency installation;
• local application startup or arbitrary command execution;
• base-versus-head preview comparison;
• observability, logs, or Sentry ingestion;
• SARIF as the authoritative receipt;
• autonomous scheduling or repeated background verification.

Those require separate evidence and product decisions.

Qualification before shipping

Implementation must prove all of the following:

• tool schema rejects unknown fields and ambiguous source selectors;
• repository scope cannot be changed by tool input;
• the target checkout remains unchanged;
• preview credentials and non-HTTP(S) URLs fail before execution;
• completed results round-trip through the canonical receipt;
• failures remain explicit and schema-valid;
• disabling verification revokes new runs;
• codevetter-mcp still exposes no execution tool;
• packaged protocol tests pass without the desktop UI.

Until then, the supported machine interface is codevetter trex --json.