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

@mcp-proxy/intercept

Quick Install