MCPRelay ⚒️

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.

💡 The Problem & The Solution

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:

1. Frontier Model (Cloud): Acts as the Architect and Reviewer (high intelligence, low token volume).

2. MCPRelay (MCP Boundary): Dispatches structured, bounded task specifications and manages local sandboxes.

3. Local Open-Source Model (Local LLM): Runs high-token implementation, editing, and test-debug loops locally with zero marginal API cost.

4. 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    │  │
   │  └────────────────────────────────────────────────────┘  │
   └──────────────────────────────────────────────────────────┘

Related MCP server: local-agent

✨ Key Features

• 📉 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.

🛠️ MCP Tools Reference

MCPRelay registers 8 native tools over standard Model Context Protocol (stdio/JSON-RPC):

🚀 Quick Start

1. Prerequisites

• Node.js: >= 20.0.0

• OpenCode CLI: Installed and accessible in PATH (npm i -g opencode-ai or 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).

2. Install & Build

git clone https://github.com/aditya1503/MCPRelay.git
cd MCPRelay
npm install
npm run build

3. Verify Health

npm run dev
# or run health check
tsx tests/v2.test.ts

4. Connect to Your AI Client

MCPRelay 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-desktop

⚙️ Configuration

Set environment variables in your environment or client config:

📊 Telemetry & Reporting

Every finished task automatically records telemetry into state/ledger.jsonl. Run the built-in rollup tool to analyze savings:

npm run rollup

Example 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

🎨 Interactive Architecture Infographic

This repository includes a standalone interactive HTML infographic diagram visualizing the complete MCP delegation flow:

open index.html

📄 License

MIT License. Designed and maintained by ADIS (Artificially Developed Intelligence Services).