code-relay-mcp
This server lets a coding agent bind a project, publish runbooks, and relay verification checkpoints to another machine via short-lived join links, then fetch and analyze structured receipts to drive repair iterations.
Bind a repository/branch as an orchestrator or checkpoint role.
Create short-lived, one-time checkpoint join invitations.
Join a branch-scoped checkpoint subscription with a URL.
Publish and validate a runbook.md for execution on the target host.
Check runbook/receipt status and load/validate receipts.
Analyze receipts to determine the next state (pass/fail/blocked).
Inspect or stop the legacy local watcher.
Run non-mutating local health checks via doctor.
Runs verification checkpoints on target hosts using a self-hosted GitHub Actions runner, validating exact source commits in isolated worktrees and returning structured receipts.
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., "@code-relay-mcp create a runbook to verify this branch on the target host"
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.
Code Relay lets your coding agent develop on one machine and prove the result on another.
Relay is an MCP-based coding-agent integration for cross-machine development and verification. AI on the Dev Host implements the request; the Target Host runs the real validation; a structured receipt comes back to guide the next repair iteration. It works with Codex, Claude Code, Cursor, VS Code, and other MCP-capable coding agents.
When Relay is useful
Different environments — develop on Windows or macOS, verify on Linux, a private network, or a production-like host.
Special hardware — send model code to a CUDA/GPU machine, or verify a camera, serial device, or sensor where it is connected.
Real integrations — exercise payment callbacks, queues, databases, browsers, or internal services that cannot be reproduced locally.
AI-driven iteration — return concrete expected/actual results so the coding agent can repair, republish, and retry.
Related MCP server: Infinite Code Next
What Relay provides
Branch-scoped project binding and short-lived join links.
Exact source-commit verification in an isolated worktree.
Checkpoint execution through a
code-relay-checkpointGitHub Actions self-hosted runner.Safe, allowlisted validation commands with bounded output and timeouts.
Structured
receipt.jsonand human-readable receipts for passed, failed, and blocked runs.
Quick start
AI client installation
Let your coding agent read and follow the instructions:
https://raw.githubusercontent.com/zarcherlot/code-relay/main/install.mdnpm fallback
npx -y code-relay-mcp@latest install --client codexReplace codex with claude-code, cursor, vscode, or generic as needed.
MCP server details
Code Relay is a local MCP server that communicates over stdio. The npm package starts the server with:
npx -y code-relay-mcp@3.1.0The server implements the MCP JSON-RPC surface directly in Go (without a
third-party MCP SDK). It supports initialize, ping, tools/list, and
tools/call, and exposes these tools:
Tool | Purpose |
| Bind a repository and branch to a relay role. |
| Create a short-lived checkpoint join link. |
| Join a branch-scoped checkpoint subscription. |
| Read local watcher state. |
| Stop the local watcher. |
| Run non-mutating local health checks. |
| Validate and publish a runbook. |
| Read runbook and receipt status. |
| Load and validate a runbook receipt. |
| Analyze a receipt and determine the next state. |
The implementation and transport loop are in internal/relay/mcp.go.
How it works
the Dev Host sends a repository- and branch-bound runbook through Relay; the Target Host checks the exact source commit in its real environment and returns a Receipt recording the Checkpoint result.
Every runbook is bound to a repository, branch, and source commit. The Target Host acts as the Checkpoint, and the resulting receipt records passed, failed, or blocked verification for the next iteration.
Documentation
License
Code Relay is released under the MIT License.
Available Tools
10 toolsanalyzeCRead-only
Analyze a runbook receipt and determine the next state.
Inputs: runbook_id (required), root.
bind_projectCDestructive
Bind the current project and branch to Code Relay.
Inputs: role (required), ref, root.
create_checkpoint_inviteC
Create a short-lived checkpoint join link.
Inputs: root, expires, one_time.
doctorCRead-only
Run non-mutating local health checks.
Inputs: root.
fetch_receiptCRead-only
Load and validate a runbook receipt.
Inputs: runbook_id (required), root.
join_checkpointCDestructive
Join a branch-scoped checkpoint subscription.
Inputs: url (required), root, destination.
publish_runbookBDestructive
Validate and publish a runbook.md.
Inputs: markdown (required), root, force, no_git.
statusCRead-only
Show runbook and receipt status.
Inputs: root.
stop_watcherCDestructive
Stop the legacy local watcher state.
Inputs: root.
watcher_statusCRead-only
Show the legacy local watcher state.
Inputs: root.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target distinct actions and resources, such as bind_project, publish_runbook, and fetch_receipt. The main ambiguity is between status and watcher_status, though their descriptions clarify that one covers runbook/receipt status and the other legacy watcher state.
Most tools follow a verb_noun pattern like create_checkpoint_invite and publish_runbook. However, doctor and status are bare nouns, and analyze is a bare verb, creating a mixed convention that is readable but not consistently patterned.
With 10 tools, the server is well-scoped for its domain. Each tool appears to cover a meaningful part of the project binding, checkpoint, and runbook workflow without unnecessary bloat.
The runbook and receipt workflow is well covered with publish, status, fetch, and analyze. However, lifecycle gaps exist: there is no unbind_project, no checkpoint leave/revoke tool, and no way to start the legacy watcher, only to stop it.
Maintenance
Related MCP Connectors
Evidence-backed project memory and checkpoints for AI coding agents.
Cryptographically anchored evidence for agents: verified run receipts, proof-gated settlement.
Browser-backed QA with evidence and fix-ready reports for coding agents.
Bounded authorization and independently verifiable execution evidence for agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceA multi-agent system that autonomously analyzes code, proves bugs with formal certificates, generates repairs, and validates patches, all over the Model Context Protocol.6MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI coding agents to keep persistent, verifiable memory of a codebase, including the reasons behind code, prior rejected approaches, and invariants, anchored to the code and carried along as the code moves.-
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to safely inspect, edit, and test code within a bounded repository environment to solve software engineering tasks and verify fixes.-
- AlicenseAqualityCmaintenanceEnables coding agents to identify the least-proven claim in code after edits and receive a focused repair packet with exact source anchors, missing proof, reproducer, and a done condition, supporting iterative verify/fix loops.3MIT