mcp-proxy

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

GitHub · Report Issue

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

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:

{
  "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:

| 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

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

# 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

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

# 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