Enables coding agents to develop on one machine and verify results on a different target host through structured runbooks and receipts.
Also known as zarcherlot/code-relay, code-relay, code-relay-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 3.1.0
- Last commit
- Oct 1, 2026
- License
- MIT
What is Code Relay MCP?
Code Relay enables coding agents to develop on one machine and verify results on a different target host through structured runbooks and receipts.
Summary generated from the project's README
About Code Relay MCP server
Coding agents that need to verify their work on different hardware or network environments can use Code Relay to bridge the gap between development and validation. By connecting a development host to a target host, an AI agent can write code on one machine and immediately prove its correctness on another, such as a Linux server, a machine with a GPU, or a device with specific sensors. This setup allows for testing real integrations like databases, payment callbacks, or internal services that are impossible to replicate locally.
The system operates as a local MCP server using stdio and is compatible with clients like Claude Code, Cursor, VS Code, and Codex. Developers use tools such as bind_project to link repositories and publish_runbook to send validation instructions. The target host executes these instructions and returns a structured receipt.json file, which the agent can then analyze to determine if it needs to repair and retry the code based on the actual results received.
What you can do with it
- 1Verify code on specialized hardwareAsk the agent to send model code to a machine equipped with a CUDA GPU for testing.
- 2Test cross-platform compatibilityHave the agent develop on a macOS environment and then run validation on a Linux target host.
- 3Automate AI-driven code repairsInstruct the agent to analyze a failed runbook receipt and perform the necessary fixes to pass the next check.
- 4Validate complex system integrationsDirect the agent to test how code interacts with live databases or message queues on a remote host.
Written from the project's README. Every use case is checked against a quote from it.
How to install Code Relay MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Code Relay MCP in Claude Code
$ claude mcp add code-relay -- npx -y code-relay-mcpInstall Code Relay MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"code-relay": {
"command": "npx",
"args": [
"-y",
"code-relay-mcp"
]
}
}
}Install Code Relay MCP in VS Code
.vscode/mcp.json
{
"servers": {
"code-relay": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"code-relay-mcp"
]
}
}
}Install Code Relay MCP in VS Code CLI
$ code --add-mcp '{"name":"code-relay","type":"stdio","command":"npx","args":["-y","code-relay-mcp"]}'Install Code Relay MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"code-relay": {
"command": "npx",
"args": [
"-y",
"code-relay-mcp"
]
}
}
}Install Code Relay MCP in Codex
$ codex mcp add code-relay -- npx -y code-relay-mcpInstall Code Relay MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.code-relay] command = "npx" args = ["-y", "code-relay-mcp"]
Install Code Relay MCP in Gemini CLI
$ gemini mcp add -s user code-relay npx -- -y code-relay-mcpInstall Code Relay MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"code-relay": {
"command": "npx",
"args": [
"-y",
"code-relay-mcp"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablezarcherlot/code-relay is public and reachablegithub.com/zarcherlot/code-relay ↗Pass
- Package names this repository as its sourcecode-relay-mcp names zarcherlot/code-relay as sourcenpmjs.com/package/code-relay-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-01github.com/zarcherlot/code-relay ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from code-relay-mcpPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCode 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.
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.md
npm fallback
npx -y code-relay-mcp@latest install --client codex
Replace 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.0
The 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_project |
Bind a repository and branch to a relay role. |
create_checkpoint_invite |
Create a short-lived checkpoint join link. |
join_checkpoint |
Join a branch-scoped checkpoint subscription. |
watcher_status |
Read local watcher state. |
stop_watcher |
Stop the local watcher. |
doctor |
Run non-mutating local health checks. |
publish_runbook |
Validate and publish a runbook. |
status |
Read runbook and receipt status. |
fetch_receipt |
Load and validate a runbook receipt. |
analyze |
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
- Chinese README
- User guide
- AI-client installation guide
- Local desktop install runbook
- Deployment and runbook
- Security
- Contributing
License
Code Relay is released under the MIT License.
Code Relay MCP questions
How do I add Code Relay MCP to Claude Code?
Run claude mcp add code-relay -- npx -y code-relay-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Code Relay MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What coding agents are compatible with Code Relay?
It works with Codex, Claude Code, Cursor, VS Code, and other MCP-capable coding agents.
What is the purpose of the Target Host in the Relay workflow?
The Target Host acts as the Checkpoint, checking the exact source commit in its real environment and returning a Receipt recording the result.