Model Context Protocol (MCP) bridge for hybrid agentic coding — delegating token-heavy implementation to local open-source models.
Architect in the cloud. Implement locally. Save 60–90% premium API tokens.
In traditional agentic coding setups, frontier models (OpenAI Codex, Claude 3.7 Sonnet / Opus) execute every step of the workflow: from high-level reasoning to reading thousands of repository lines, running test suites, and fixing compiler errors.
This is extremely expensive and inefficient:
- Over 80% of total tokens are consumed in repetitive, mechanical loops (file discovery, syntax fixes, unit-test iterations).
- Proprietary codebase context is repeatedly streamed to external cloud APIs.
MCPRelay solves this with Hybrid Agentic Coding:
- Frontier Model (Cloud): Acts as the Architect and Reviewer (high intelligence, low token volume).
- MCPRelay (MCP Boundary): Dispatches structured, bounded task specifications and manages local sandboxes.
- Local Open-Source Model (Local LLM): Runs high-token implementation, editing, and test-debug loops locally with zero marginal API cost.
- Frontier Review: The cloud model inspects only the concise diff, logs, and summary to verify correctness.
┌──────────────────────────────────────────────────────────┐
│ 1. ARCHITECT / REVIEWER │
│ (Codex / Claude) │
│ • Understands requirement • Reviews diff & logs │
└────────────────────────────┬─────────────────────────────┘
│
[MCP Task Specification]
│
▼
┌──────────────────────────────────────────────────────────┐
│ 2. MCPRELAY (MCP) │
│ • Session continuity • Privacy boundary │
│ • Cross-process locks • Telemetry ledger │
└────────────────────────────┬─────────────────────────────┘
│
[Local Inference Stream]
│
▼
┌──────────────────────────────────────────────────────────┐
│ 3. IMPLEMENTATION WORKER │
│ (DeepSeek V4 Flash / Qwen 2.5 / 3.5) │
│ ┌────────────────────────────────────────────────────┐ │
│ │ 🔄 LOCAL ITERATION LOOP │ │
│ │ Read Repo ➔ Edit Code ➔ Run Tests ➔ Fix Errors │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
- 📉 60–90% Premium Token Reduction: Keeps token-intensive code edits, file indexing, and test-debugging entirely on local hardware.
- 🛡️ Strict Privacy & Security Boundaries: Sensitive internal files and multi-round diagnostic dumps stay inside your local network.
- 🔄 Session Continuity: Multi-turn follow-ups (
opencode_followup) resume the same execution session without re-sending the whole repository context. - 🔒 Cross-Process Repository Locking: Prevents conflicting concurrent writes across multiple agent tabs or clients.
- 📊 Telemetry & Audit Ledger: Automatic recording of execution duration, files touched, lines added/deleted, and estimated token savings to
state/ledger.jsonl. - ⚡ Zero-Config Client Registration: Single command setup for Codex, Claude Code, Claude Desktop, and Antigravity.
MCPRelay registers 8 native tools over standard Model Context Protocol (stdio/JSON-RPC):
| Tool | Description |
|---|---|
opencode_implement |
Dispatches a bounded task specification (goal, constraints, interfaces, context) to the local worker. |
opencode_wait |
Single blocking wait until a running task reaches terminal state (completed / failed). Replaces status polling loops. |
opencode_status |
Non-blocking status snapshot of an active or finished task. |
opencode_diff |
Returns a scoped git diff of changes made by the local worker against the baseline commit. |
opencode_followup |
Resumes an existing OpenCode session to fix defects, adjust edge cases, or add tests based on review feedback. |
opencode_cancel |
Gracefully terminates a running task and its child processes. |
opencode_health |
Checks local model endpoint availability, opencode CLI health, and active model configuration. |
opencode_history |
Queries past delegation outcomes, duration, and success rates for a given repository. |
- Node.js:
>= 20.0.0 - OpenCode CLI: Installed and accessible in
PATH(npm i -g opencode-aior binary) - Local Inference Model: A running OpenAI-compatible endpoint (e.g. DeepSeek V4 Flash, Qwen 2.5/3.5 on vLLM, Ollama, SGLang, or dual DGX Spark clusters).
git clone https://github.com/aditya1503/MCPRelay.git
cd MCPRelay
npm install
npm run buildnpm run dev
# or run health check
tsx tests/v2.test.tsMCPRelay includes an automated client registrar script:
# Register with OpenAI Codex / Antigravity
node scripts/register-client.mjs antigravity
# Register with Claude Code
node scripts/register-client.mjs claude-code
# Register with Claude Desktop
node scripts/register-client.mjs claude-desktopSet environment variables in your environment or client config:
| Variable | Default | Description |
|---|---|---|
OPENCODE_MODEL |
spark/deepseek-v4-flash-0731 |
Model identifier passed to OpenCode. |
WORKER_HEALTH_URL |
http://127.0.0.1:8890/v1/models |
Health endpoint for the local inference server. |
ALLOWED_REPO_ROOT |
Current working directory | Root directory whitelist to prevent path traversal. |
TASK_TIMEOUT_MS |
600000 (10 mins) |
Maximum execution time before automatic termination. |
Every finished task automatically records telemetry into state/ledger.jsonl. Run the built-in rollup tool to analyze savings:
npm run rollupExample Output:
=== MCPRelay Telemetry Rollup ===
Total Tasks: 42
Success Rate: 95.2%
Avg Task Duration: 28.4s
Estimated Cloud Tokens Saved: ~1.85M tokens
Top Task Classes: unit-test-generation, bugfix, refactoring
This repository includes a standalone interactive HTML infographic diagram visualizing the complete MCP delegation flow:
open index.htmlMIT License. Designed and maintained by ADIS (Artificially Developed Intelligence Services).