mcp-context-proxy

MCP Context Proxy (MCPCP)

A transparent MCP (Model Context Protocol) proxy that compresses large tool responses using an external LLM before passing them to resource-constrained local models.

This project is meant for personal use, and no guarantees are made for mission critical production environments... or whatever your environment is. Yeah, it's vibe coded. Trust it as much as you'd trust any other random code you find on the web.

TL;DR: It's faster

• Use smaller models to summarize/extract content from any MCP response, saving time and context with your main model. Stop trying to engineer around bloated MCP responses and get your agent the data it needs.
• Uses caching for repeated, identical tool calls to save even more time and reduce API calls
• Tweak MCPs to your liking - disable tools, overwrite descriptions for better accuracy and SMALLER CONTEXT (see the theme yet?)
• A single configuration of all your upstream MCPs, so you can try different interfaces/coding agents without needing to setup all your MCPs each time
• Future looking - pre- and post- hooks to strip PII or check for prompt injection

Where'd this come from?

For those of us running LLMs locally, especially at home, context costs us time, not just tokens. This project was borne out of frustration with MCPs that are little more than "API wrappers" and would respond with often much more information than I needed, eating up valuable context and taking up time while I waited for the prompt processing to complete.

I wanted to see how a tiny LLM/SLM could help compress MCP outputs before responding back to the client LLM. That worked, and then I started adding in more functionality to make this a helpful little Swiss Army Knife for enthusiasts like myself... but like a really tiny Swiss Army Knife, not one of those obscene behemoths.

Ok, so how do I use it?

Let's say you're running Llama.cpp locally with something like gpt-oss-120b. You have the usual fetch and maybe searxng MCPs set up doing some basic web search and URL retrieval. But processing those pages is taking forever and adding useless context. So you allocate a little VRAM, or even regular RAM, to Qwen3-0.6B or LFM2-1.2B and set up MCPCP for your MCPs. Now if the response size exceeds a configured token count, your small model performs an extraction/summary against the content and returns that back to your larger model, saving time.

I realized that an alternative to running a small LLM locally could also be "offshoring" compression of certain MCP responses to zero-cost or low cost cloud models. Perhaps you want to do as much as you can locally, but don't mind having a cloud model read public web pages that searxng finds. You could have you local model hand that off to a cloud model to compress and then give you back what you need to know from that page, without compromising privacy. To that end, I'm also experimenting with adding some PII-preserving functions with combinations of regex and LLM.

Maybe you're not using sammcj/mcp-devtools (you should) or there's a MCP that helps solve a very specific need, but you don't need most of the tools it offers. So every time your LLM runs, you're burning initial tokens with those extra tool references. Rather than reinventing the upstream MCP, you can use mcp-context-proxy to disable those tools, so your client LLM never sees them in the first place, increasing performance and saving time.

MCP Client (Claude Desktop, Cursor, etc.)
    ↓
mcp-context-proxy
    ↓ ←── Compression Model (OpenAI-compatible)
Upstream MCP Server(s)

Features

• Transparent proxy - Works with any MCP client and server
• Smart compression - Auto-detects content type (JSON, code, text) and applies appropriate compression strategy, with per-tool configurability
• Response caching - Caches compressed responses to avoid redundant LLM calls (near-instant response time on cache hits)
• Tool hiding - Hide unwanted tools to reduce context pollution and improve model focus
• Description overrides - Customize tool descriptions to better steer client LLM behavior
• PII masking - Mask sensitive data (emails, SSNs, phone numbers, etc.) before sending to upstream servers
• Multi-server aggregation - Connect to multiple upstream MCP servers simultaneously
• All transports - Supports stdio, SSE, and Streamable HTTP for both upstream and downstream
• Per-tool policies - Configure different compression thresholds and masking rules for different tools

Installation

npm install -g mcp-context-proxy

Or run directly with npx:

npx mcp-context-proxy --help

For deployment options (PM2, Docker), see INSTALLATION.md.

Quick Start

1. Generate a config file:

mcp-context-proxy --init

2. Edit mcpcp.config.json to configure your upstream servers and compression model:

{
  "version": 2,
  "downstream": {
    "transport": "stdio"
  },
  "upstreams": [
    {
      "id": "my-server",
      "name": "My MCP Server",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  ],
  "defaults": {
    "compression": {
      "enabled": true,
      "tokenThreshold": 1000,
      "maxOutputTokens": 500,
      "goalAware": true
    },
    "cache": {
      "enabled": true,
      "ttlSeconds": 300
    }
  },
  "compression": {
    "baseUrl": "http://localhost:8080/v1",
    "model": "your-model"
  },
  "cache": {
    "maxEntries": 1000,
    "cacheErrors": true
  }
}

3. Run the proxy:

mcp-context-proxy

Web Dashboard

When running with HTTP transports (sse or streamable-http), MCPCP provides a web dashboard for monitoring and configuration.

Accessing the Dashboard

The dashboard is available at the root URL of your proxy:

http://localhost:3000/

(Replace localhost:3000 with your configured host and port)

Note: The dashboard is only available with HTTP transports. When using stdio transport, there is no HTTP server and thus no dashboard.

Dashboard Features

The dashboard has three tabs: Configuration (default), Logs, and Status.

Configuration Editor

The default tab provides a JSON editor for modifying your proxy configuration:

1. View current config - The editor loads your active configuration
2. Edit inline - Modify settings directly in the browser
3. Validate - Configuration is validated before applying
4. Hot reload - Click "Apply & Reload" to apply changes without restarting the proxy

Hot reload will:

• Disconnect from old upstreams
• Apply the new configuration
• Reconnect to upstreams (including any new ones)
• Refresh all aggregated tools, resources, and prompts

Tip: Keep the Logs tab open while reloading to monitor the reconnection process.

Logs

Streams proxy logs in real-time via SSE:

• Log levels - Filter by debug, info, warn, error
• Auto-scroll - Automatically follows new log entries
• Searchable - Find specific log messages

Useful for debugging compression behavior, upstream connection issues, or cache hits/misses.

Status

Shows proxy status and upstream connections:

• Proxy status - Whether the proxy is running and healthy
• Upstream connections - Each connected MCP server with its connection status
• Tool/Resource/Prompt counts - Number of items aggregated from each upstream

Click on any upstream to expand and see its full list of tools, resources, and prompts.

API Endpoints

The dashboard uses these API endpoints, which are also available for programmatic access:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/status | GET | Current proxy and upstream status | | /api/status/:upstreamId | GET | Details for a specific upstream | | /api/config | GET | Current configuration (JSON) | | /api/config | PUT | Save configuration to disk | | /api/config/validate | POST | Validate configuration without saving | | /api/reload | POST | Reload configuration from disk | | /api/logs/stream | GET | SSE stream of real-time logs | | /health | GET | Health check endpoint |

Configuration

MCPCP supports a flexible configuration system with a three-level hierarchy (global defaults → upstream defaults → tool-specific) for controlling compression, masking, and caching behaviors. This eliminates repetition and allows precise control when needed.

For practical examples, use cases, and detailed guidance, see CONFIGURATION.md.

Configuration File

• Default location: mcpcp.config.json in the current directory
• Custom location: Use --config <path> flag
• Generate template: Run mcp-context-proxy --init
• Current version: version: 2 (Migration from v0.3.x)

Downstream (Client-facing)

| Field | Type | Description | |-------|------|-------------| | transport | "stdio" \| "sse" \| "streamable-http" | Transport protocol | | port | number | Port for HTTP transports | | host | string | Host to bind for HTTP transports |

Upstreams (MCP Servers)

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier (used for tool namespacing) | | name | string | Human-readable name | | transport | "stdio" \| "sse" \| "streamable-http" | Transport protocol | | command | string | Command to run (stdio only) | | args | string[] | Command arguments (stdio only) | | url | string | Server URL (HTTP transports) | | enabled | boolean | Enable/disable this upstream |

Compression

Infrastructure Settings

The top-level compression object configures where and how to connect to the compression LLM:

| Field | Type | Description | |-------|------|-------------| | baseUrl | string | OpenAI-compatible API base URL | | apiKey | string | API key (optional for local models) | | model | string | Model identifier | | bypassEnabled | boolean | Inject _mcpcp_bypass field to allow skipping compression (default: false) | | retryEscalation | object | Auto-increase output on repeated tool calls (see below) |

Compression Policy

Compression policies (when/how to compress) are configured via the three-level hierarchy: defaults.compression, upstreams[].defaults.compression, upstreams[].tools[name].compression

Resolution: Tool-specific > Upstream defaults > Global defaults > Built-in defaults

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Enable/disable compression (default: true) | | tokenThreshold | number | Minimum tokens to trigger compression (default: 1000) | | maxOutputTokens | number | Maximum tokens in compressed output | | goalAware | boolean | Inject _mcpcp_goal field into tool schemas (default: true) | | customInstructions | string | Additional instructions for compression LLM |

See: CONFIGURATION.md - Use Cases for practical examples

Retry Escalation

Automatically increases maxOutputTokens on repeated tool calls within a sliding window when compression may have removed needed information.

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Enable retry escalation (default: true) | | windowSeconds | number | Sliding window to track calls (default: 60) | | tokenMultiplier | number | Linear multiplier per retry (default: 2) |

Behavior: 1st call uses normal maxOutputTokens, 2nd call within window uses maxOutputTokens * 2, 3rd uses maxOutputTokens * 3, etc.

See: CONFIGURATION.md - Retry Escalation Pattern for detailed examples

Compression Metadata

All compressed responses include a metadata header:

[Compressed: 14246→283 tokens, strategy: json]
[Compressed: 14246→566 tokens, strategy: json, escalation: 2x]

Format: [Compressed: {original}→{compressed} tokens, strategy: {json|code|default}, escalation: {multiplier}]

Bypass Field

When bypassEnabled: true, adds _mcpcp_bypass field to all tool schemas. Clients can set this to true to receive the full uncompressed response.

See: CONFIGURATION.md - Bypass Pattern

Cache

Infrastructure Settings

The top-level cache object configures cache infrastructure:

| Field | Type | Description | |-------|------|-------------| | maxEntries | number | Maximum cache entries (default: 1000) | | cacheErrors | boolean | Cache error responses (default: true) |

Cache Policy

Cache policies (when/how long to cache) are configured via the three-level hierarchy: defaults.cache, upstreams[].defaults.cache, upstreams[].tools[name].cache

Resolution: Tool-specific > Upstream defaults > Global defaults > Built-in defaults

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Enable/disable caching (default: true) | | ttlSeconds | number | Cache entry TTL in seconds (default: 300) |

Cache Key: tool name + arguments + normalized goal

Goal Normalization: Lowercase + removes all punctuation. Examples: "Find API!" → "find api", "What's this?" → "whats this"

See: CONFIGURATION.md - Aggressive Caching for practical examples

Tool Configuration

Configure individual tools within each upstream's tools object using the tool's original name (not namespaced):

| Field | Type | Description | |-------|------|-------------| | hidden | boolean | Hide this tool from clients (default: false) | | compression | object | Per-tool compression policy overrides | | masking | object | Per-tool PII masking policy overrides | | cache | object | Per-tool cache policy overrides | | overwriteDescription | string | Replace the tool's description | | hideParameters | string[] | Parameters to hide from client schema | | parameterOverrides | object | Server-side parameter injection |

Hiding Tools

Set hidden: true to prevent tools from appearing in tools/list. Hidden tools are rejected if called directly.

See: CONFIGURATION.md - Hiding Unwanted Tools

Description Overrides

Use overwriteDescription to replace a tool's description and control LLM behavior. If goalAware is enabled, the _mcpcp_goal instruction is auto-appended.

See: CONFIGURATION.md - Description Overrides Pattern

Parameter Hiding & Overrides

• hideParameters: Array of parameter names to remove from client schema
• parameterOverrides: Object of parameter name → value mappings for server-side injection

Rules:

• All hidden parameters MUST have corresponding overrides (validated at config load)
• Overrides are applied BEFORE PII masking
• Overrides take precedence over client-provided values

See: CONFIGURATION.md - Optimizing Web Fetch

PII Masking (Experimental)

Protects sensitive data by masking before forwarding to upstreams and restoring before returning to the client.

Flow: Client → [MASK] → Upstream → [RESTORE] → Client

Infrastructure Settings

The top-level masking object configures infrastructure and acts as a master switch:

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Master switch - must be true for any masking to work (default: false) | | llmConfig | object | Optional LLM config for fallback detection |

Important: Even if policies enable masking, it won't run unless the global master switch is enabled.

Masking Policy

Masking policies are configured via the three-level hierarchy: defaults.masking, upstreams[].defaults.masking, upstreams[].tools[name].masking

Resolution: Tool-specific > Upstream defaults > Global defaults > Built-in defaults

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Enable/disable masking for this tool | | piiTypes | string[] | PII types to mask (default: ["email", "ssn", "phone", "credit_card", "ip_address"]) | | llmFallback | boolean | Use LLM for ambiguous cases (default: false) | | llmFallbackThreshold | "low" \| "medium" \| "high" | Trigger LLM for patterns at or below this confidence (default: "low") | | customPatterns | object | Custom regex patterns |

Supported PII Types

Placeholders are numbered sequentially per type starting from 1 (e.g., [EMAIL_1], [EMAIL_2], [EMAIL_3], ...) to allow proper restoration of unique values.

| Type | Placeholder Format | Confidence | Example | |------|-------------------|------------|---------| | email | [EMAIL_n] | high | [email protected] | | ssn | [SSN_n] | medium | 123-45-6789 | | phone | [PHONE_n] | medium | 555-123-4567 | | credit_card | [CREDIT_CARD_n] | high | 4111111111111111 | | ip_address | [IP_n] | high | 192.168.1.100 | | date_of_birth | [DOB_n] | high | 01/15/1990 (only with DOB/birth keywords) | | passport | [PASSPORT_n] | low | A12345678 | | driver_license | [DL_n] | low | D1234567 |

Note: Low-confidence patterns (passport, driver_license) may produce false positives. Consider using llmFallback: true for these.

See: CONFIGURATION.md - PII Protection for complete examples

Tool Namespacing

Tools from upstream servers are namespaced to avoid conflicts:

• Original tool: read_file
• Namespaced: {upstream_id}__read_file

Compression Strategies

mcp-context-proxy auto-detects content type and applies the appropriate strategy:

| Strategy | Trigger | Behavior | |----------|---------|----------| | code | Function definitions, imports, class syntax | Preserves signatures, summarizes implementation | | json | Valid JSON | Preserves structure, shortens values | | default | Everything else | General text compression |

Requirements

• Node.js 24+
• TypeScript 5.x

Key Dependencies

| Package | Version | Purpose | |---------|---------|---------| | @modelcontextprotocol/sdk | 1.25.x | MCP protocol implementation | | ai / @ai-sdk/openai-compatible | 6.x / 2.x | LLM API client (Vercel AI SDK) | | ai-tokenizer | 1.x | Token counting (o200k_base encoding) | | express | 5.x | HTTP server for SSE/Streamable HTTP transports | | zod | 4.x | Configuration schema validation | | winston | 3.x | Logging |

License

MIT