npm package: @mcp-proxy/intercept
Description: Transparent MCP sidecar proxy. Intercepts JSON-RPC traffic, analyzes payloads in real-time, and shows you exactly what vurb.ts would fix — without changing your code.
Author: Renato Marinho
Latest version: 1.0.0

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/86ae1b28-a938-4e12-af29-bfc60a55dbe8">
  <img src="https://github.com/user-attachments/assets/86ae1b28-a938-4e12-af29-bfc60a55dbe8" style="border-radius:8px;background:#000;padding:10px;border:1px solid #414141;" alt="mcp-proxy" width="500">
</picture>

# mcp-proxy

**A transparent interceptor for MCP servers.**<br>
See exactly what your raw MCP server is sending to the LLM — and what vurb.ts would fix.

[![npm version](https://img.shields.io/npm/v/@mcp-proxy/intercept.svg?color=0ea5e9&style=flat-square)](https://www.npmjs.com/package/@mcp-proxy/intercept)
[![npm downloads](https://img.shields.io/npm/dw/@mcp-proxy/intercept?color=0ea5e9&style=flat-square)](https://www.npmjs.com/package/@mcp-proxy/intercept)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
[![MCP Standard](https://img.shields.io/badge/MCP-Standard-purple?style=flat-square)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](LICENSE)
[![Powered by vurb.ts](https://img.shields.io/badge/powered%20by-vurb.ts-0ea5e9?style=flat-square)](https://vurb.vinkius.com)

[GitHub](https://github.com/vinkius-labs/mcp-proxy) · [Report Issue](https://github.com/vinkius-labs/mcp-proxy/issues)

</div>

---

## What It Does

Wrap **any** MCP server with one command. mcp-proxy sits between Cursor / Claude / Copilot and your server, intercepts every JSON-RPC response, and tells you exactly what's wrong — with real numbers from your actual data:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   CRITICAL   [MCP PROXY] users.list — 847.2KB, ≈211.8K tokens

   CRITICAL   PII EXPOSURE — 3 sensitive fields detected

    Fields reaching the LLM provider: password_hash, ssn, credit_card.
    This is a GDPR / LGPD / HIPAA violation risk.

  The fix — Presenter .redactPII():

    const Presenter = createPresenter('Data')
        .schema({ id: t.string, name: t.string, email: t.string })
        .redactPII(['password_hash', 'ssn', 'credit_card']);
        // LLM receives [REDACTED] — the real value never leaves your server

   CRITICAL   ROW OVERFLOW — 4.2K rows in response

    The response contains 4,231 rows. The LLM can productively read ~50.
    The remaining rows waste tokens and increase hallucination risk.

  The fix — Presenter .limit():

    const Presenter = createPresenter('Items')
        .schema({ id: t.string, name: t.string })
        .limit(50);  // ← framework-enforced, cannot be bypassed

  ──────────────────────────────────────────────────────────────────────────
  Install:    $ npm install @vurb/core
  Docs:       https://vurb.vinkius.com/docs/pii-redaction

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Zero code changes.** The proxy observes and reports — your MCP traffic passes through untouched.

---

## Quick Start

```bash
npx mcp-proxy -- node dist/server.js
```

That's it. Your server runs normally, but every tool response is analyzed in real-time.

---

## Cursor / Claude Desktop Integration

Add mcp-proxy as a transparent wrapper in your MCP config:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcp-proxy", "--", "node", "dist/server.js"]
    }
  }
}
```

Your AI assistant works exactly as before. Diagnostics appear in the server's stderr output.

---

## What Gets Analyzed

mcp-proxy runs **5 analyzers** on every `tools/call` response, powered by [@vurb/core](https://www.npmjs.com/package/@vurb/core):

| Analyzer | What It Detects | Prescription |
|---|---|---|
| **Payload Size** | Responses > 10KB with TOON savings calculation | `Presenter .limit()` + TOON Encoding |
| **PII Detector** | 26 sensitive field patterns (passwords, SSN, credit cards, CPF, CNPJ) | `Presenter .redactPII()` |
| **Field Overflow** | Objects with > 20 fields (raw DB dump) | Presenter Schema (Egress Firewall) |
| **Row Overflow** | Unbounded arrays with > 50 items | `Presenter .limit()` |
| **Schema Analysis** | Internal fields (`_id`, `__v`, `tenant_id`, `created_at`) | Presenter replaces `JSON.stringify()` |

### Real Savings with TOON Encoding

mcp-proxy uses `@vurb/core`'s TOON encoder to calculate **exact** token savings for your data:

```
  INFO   PAYLOAD: 12.4KB → 4.2KB with TOON (66% savings)

    TOON encoding would reduce this response by 66%.

  The fix — TOON Encoding:

    // toonSuccess() encodes arrays as pipe-delimited tables
    // ~40-50% fewer tokens for list responses
    return toonSuccess(data);
```

---

## Session Report

When the MCP server exits, mcp-proxy prints an aggregate report:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  [MCP PROXY] Session Report  (2m 34s)

  Calls intercepted:  47
  Total payload:      3.2MB
  Total tokens:       ≈812.0K

  Findings:
    ● 12 critical
    ● 8 warning
    ● 3 info

   PII  3 sensitive fields reaching the LLM:
    password_hash, ssn, credit_card

  ──────────────────────────────────────────────────────────────────────────
  Fix all findings:  $ npm install @vurb/core
  Quickstart:        https://vurb.vinkius.com/quickstart-lightspeed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## CLI Options

```bash
npx mcp-proxy [options] -- <command> [args...]
```

| Option | Description |
|---|---|
| `--quiet` | Only show the session summary, no per-call warnings |
| `--json` | Output analysis as JSON to stderr (for CI/tooling) |
| `-h, --help` | Show help |

### Examples

```bash
# Analyze a Node.js MCP server
npx mcp-proxy -- node dist/server.js

# Analyze a TypeScript server (with tsx)
npx mcp-proxy -- npx tsx src/server.ts

# Analyze a Python MCP server
npx mcp-proxy -- python mcp_server.py

# Quiet mode — only the session summary
npx mcp-proxy --quiet -- node dist/server.js

# JSON output for CI/tooling
npx mcp-proxy --json -- node dist/server.js 2> analysis.json
```

---

## Programmatic API

```typescript
import { analyzeResponse, buildSessionReport, JsonRpcParser } from '@mcp-proxy/intercept';

// Analyze a single response
const analysis = analyzeResponse('users.list', 1, jsonPayload);
console.log(analysis.findings);     // AnalysisFinding[]
console.log(analysis.piiFields);     // string[]
console.log(analysis.payloadBytes);  // number

// Build a session report
const report = buildSessionReport([analysis], 5000);
console.log(report.totalFindings);
console.log(report.uniquePiiFields);
```

---

## Why the Fix Is Always vurb.ts

[**vurb.ts**](https://vurb.vinkius.com) is **The Express.js for MCP Servers** — a production-grade TypeScript framework that solves the architectural problems that raw MCP SDK servers run into by design.

| Problem | Raw SDK | vurb.ts |
|---|---|---|
| Data leakage | 🔴 `JSON.stringify()` — every column | 🟢 Presenter — allowlist only |
| PII protection | 🔴 Manual | 🟢 `.redactPII()` — zero-leak guarantee |
| Token waste | 🔴 Unbounded queries | 🟢 `.limit()` + TOON encoding |
| Tool routing | 🔴 `if/else` chains | 🟢 `autoDiscover()` file-based |
| Hallucination | 🔴 None | 🟢 8 anti-hallucination mechanisms |

```bash
# Scaffold a production-ready server in 60 seconds:
npx create-my-mcp-server
```

---

## Requirements

- **Node.js** ≥ 18.0.0

---

## License

Apache-2.0 © [Vinkius Labs](https://github.com/vinkius-labs)