MCP Smart Proxy
Intelligent proxy for Model Context Protocol (MCP) — fewer tokens, focused context, everything runs locally. No data leakage.
🎯 Why MCP Smart Proxy?
An optimization layer for the Model Context Protocol (MCP). Traditional implementations waste up to 81% of the context window (Cloudflare); this proxy cuts that to 10–30%.
| Benefit | Explanation |
|---|---|
| 💰 Fewer tokens | 70–90% less token consumption → lower cost, less waste. |
| 🎯 More precise LLM | Smaller, focused context → less noise, fewer hallucinations. |
| 🔒 Secure, no leakage | Runs entirely locally; no prompts or data sent to third parties. |
✨ Key Features
- Semantic Routing — Routes requests to the most relevant tools
- Semantic Cache — Returns cached MCP responses when queries are semantically similar (see Semantic Cache)
- Vector-Based Memory — Local embeddings (e.g. Xenova/all-MiniLM), no external API
- Tool Aggregation — Unified interface for multiple MCP servers
- Performance Monitoring — Real-time analytics and dashboard
- Streamable HTTP — Upstream MCP servers use HTTP(S) endpoints (MCP Streamable HTTP), aligned with modern MCP clients (e.g.
type: "streamable"where supported). MIT licensed.
⚡ Start quickly
The proxy exposes MCP Streamable HTTP on POST /mcp. You configure two things: (1) which upstream MCP servers the proxy calls (config/default.json in this repo), and (2) where your MCP client sends traffic (your editor or agent’s MCP settings — file path depends on the product — pointing at your proxy URL).
1. Run the proxy```bash
git clone https://github.com/Mourad95/mcp-smart-proxy.git
cd mcp-smart-proxy
npm ci
npm run build
node dist/index.js start --config ./config/default.json
Check: `curl http://localhost:3000/health` → `status: healthy`.
Default port is **3000** (see `port` in `config/default.json` or pass `--port 3000`).
### 2. Configure upstream MCP servers (inside this repo)
Edit **`config/default.json`** (or pass another file with `--config`). Under **`mcpServers`**, list each **remote MCP** the proxy should use. Each **`url`** must be a **Streamable HTTP** MCP URL (`http://` or `https://`, usually ending with `/mcp`).
Example (data.gouv.fr MCP):```json
"mcpServers": [
{
"name": "datagouv",
"url": "https://mcp.data.gouv.fr/mcp",
"description": "data.gouv.fr",
"enabled": true,
"timeout": 60000
}
]
- Set
"enabled": truefor every server you want active. - Optional
headers(e.g. Composiox-api-key) are sent on every request to that upstream. - Restart the proxy after editing the file.
This file is only read by the proxy process. Your IDE does not open it directly.
3. Point your MCP client at the proxy (not at data.gouv directly)
In your client’s MCP configuration, add a streamable HTTP endpoint whose url is the proxy base URL including /mcp (exact file location depends on the editor or agent). Example shape:```json
{
"mcpServers": {
"mcp-smart-proxy": {
"type": "streamable",
"url": "http://127.0.0.1:3000/mcp"
}
}
}
Reload or restart the client so it picks up the change. Traffic flow: **MCP client** → `http://127.0.0.1:3000/mcp` → **proxy** → upstream URLs from step 2 (e.g. `https://mcp.data.gouv.fr/mcp`).
For **Claude Desktop** and clients that use `mcp-remote` to bridge HTTP MCP, point `mcp-remote` at the same proxy URL (`http://127.0.0.1:3000/mcp`) instead of the upstream server.
**Health & metrics:** `curl http://localhost:3000/health` · `curl http://localhost:3000/metrics` · Dashboard: `http://localhost:3000/dashboard` (if enabled and built).
### Other install options
| Method | Command |
|--------|---------|
| **Docker Compose** | `make docker-compose` then `curl http://localhost:3000/health` |
| **Makefile** | `make install && make build && make run` (or `make dev`) |
| **Global CLI** | `npm install -g mcp-smart-proxy` then `mcp-smart-proxy start --config ./config/default.json` |
Smoke scripts (optional): `node scripts/smoke-http.mjs` (no upstream), `node scripts/smoke-mcp-http.mjs` (requires upstream enabled + network).
## 📊 The problem: context waste & hallucinations
Traditional MCP wastes **81%** of the context (unnecessary tool descriptions, irrelevant context, duplication, poor tool choice). That also increases hallucinations — the model gets too much noise and fills gaps by inventing details.
**Our approach:** intelligent tool filtering, semantic context selection, deduplication, and optimized routing so the model receives less but targeted context → fewer hallucinations, better reliability.
## 🔒 Security and privacy
Runs entirely on your side: proxy, embeddings, and vector indexes stay on your machine or infra — **no prompts or data sent to third parties**. Responses are sanitized (API keys, tokens, DB URLs masked). You control which MCP servers and embedding models run where. See **SECURITY.md** for rate limiting, validation, and deployment.
## 🏗️ Architecture```mermaid
flowchart LR
subgraph client[" "]
A["MCP client"]
end
subgraph proxy[" "]
B["MCP Smart Proxy"]
end
subgraph servers[" "]
C[GitHub]
D[SQLite]
E[Filesystem]
F[Custom...]
end
A -->|"request"| B
B --> C
B --> D
B --> E
B --> F
C --> B
D --> B
E --> B
F --> B
B -->|"optimized response"| A
In one glance: the client talks only to the proxy; the proxy picks the right MCP servers (GitHub, SQLite, filesystem, etc.), trims context, and returns a lean answer — fewer tokens, fewer hallucinations, everything local.
Internal components (ASCII)```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Client │ │ Smart Proxy │ │ MCP Servers │
│ (Claude, etc.)│ │ │ │ │
│ │ │ ┌───────────┐ │ │ ┌───────────┐ │
│ ┌───────────┐ │ │ │ Semantic │ │ │ │ Tool A │ │
│ │ Query │──┼───▶│ │ Router │──┼───▶│ │ │ │
│ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │
│ │ │ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Optimized │◀─┼────│ │ Context │◀─┼────│ │ Tool B │ │
│ │ Response │ │ │ │ Optimizer │ │ │ │ │ │
│ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ ┌───────────┐ │
│ │ Vector │ │
│ │ Memory │ │
│ └───────────┘ │
└─────────────────┘
## ⚙️ Configuration
### Basic configuration
Use **`config/default.json`** (or copy it). Each **`mcpServers[].url`** is the **upstream** Streamable HTTP MCP endpoint (not the proxy URL).
### Secrets and `config/local.json` (not committed)
Put **API keys and machine-only overrides** in **`config/local.json`** in the **same directory** as the config file you pass to `--config` (e.g. `config/local.json` next to `config/default.json`). That file is **gitignored** and **merged** after the main file: top-level keys override, and **`mcpServers`** entries are merged **by `name`** (so you can add e.g. only `headers` for `composio`). Copy **`config/local.example.json`** to **`config/local.json`** and replace placeholders. **Rotate any secret that was ever committed** to the repository.
Example committed main file (no API keys in git):```json
{
"port": 3000,
"mcpServers": [
{
"name": "datagouv",
"url": "https://mcp.data.gouv.fr/mcp",
"description": "Example upstream MCP",
"enabled": true,
"timeout": 60000
}
],
"optimization": {
"enabled": true,
"maxContextTokens": 1000,
"embeddingModel": "Xenova/all-MiniLM-L6-v2",
"cacheEnabled": true,
"semanticRouting": true,
"minRelevanceScore": 0.3
},
"logging": { "level": "info", "format": "text" },
"analytics": { "enabled": true, "retentionDays": 30, "dashboardEnabled": true }
}
tools/list optimization: When optimization.enabled is true, every tools/list runs the same optimizeContext path. If the client sends params.context.query, that string is used; otherwise toolsListOptimizationQuery (or env MCP_TOOLS_LIST_OPTIMIZATION_QUERY) supplies the default. If semantic filtering would remove every tool, the proxy falls back to the full tool list. When optimization is disabled, the proxy returns the full catalog (pass-through) and records catalog metrics.
Environment Variables```bash
Proxy configuration
export MCP_PROXY_PORT=3000
export MCP_PROXY_LOG_LEVEL=info
Optimization settings
export MCP_OPTIMIZATION_ENABLED=true
export MCP_MAX_CONTEXT_TOKENS=1000
Vector memory
export MCP_VECTOR_MEMORY_PATH="./.mcp-vector-index"
export MCP_EMBEDDING_MODEL="Xenova/all-MiniLM-L6-v2"
Optimization statistics and dashboard data (default: ./data/stats)
export MCP_STATS_DIR="./data/stats"
### Data storage
Optimization statistics and dashboard data are stored on disk so they survive restarts.
| Location | Content |
|----------|---------|
| **`MCP_STATS_DIR`** (default: `./data/stats`) | Directory for optimization stats. Contains `optimization-stats.json` (aggregated metrics: total requests, token savings, hourly breakdown, top tools), plus logs (`optimization.log`, `stats.json`). |
| **`./data/reports`** | Exported reports (JSON/CSV) when using the dashboard “Export report” or the `/api/reports/export` endpoint. |
Set `MCP_STATS_DIR` to change where stats are written (e.g. `/data/stats` in Docker). The “Recent requests” list in the dashboard is in-memory only and is cleared on proxy restart.
## 📁 Project structure (overview)```
mcp-smart-proxy/
├── src/
│ ├── index.ts # CLI entry (start, analyze, maintenance)
│ ├── proxy/
│ │ ├── server.ts # Express: /health, /mcp, /optimize, /proxy/:name, …
│ │ └── mcp-http-transport.ts # MCP Streamable HTTP client to upstream servers
│ ├── optimization/
│ │ └── context-optimizer.ts
│ ├── memory/
│ │ └── vector-memory.ts
│ ├── cache/
│ │ └── semantic-cache.ts
│ ├── analytics/
│ ├── config/
│ └── types/
├── config/ # default.json, production.json, local-smoke.json
├── scripts/ # smoke-http.mjs, smoke-mcp-http.mjs
├── dashboard/ # Optional React dashboard (build with npm run build:full)
├── docs/ # e.g. SEMANTIC-CACHE.md
└── package.json
📈 Performance Metrics
Token savings
| Scenario | Traditional MCP | Smart Proxy | Savings |
|---|---|---|---|
| Simple Query | 1,000 tokens | 300 tokens | 70% |
| Complex Query | 5,000 tokens | 1,000 tokens | 80% |
| Multi-tool | 10,000 tokens | 2,000 tokens | 80% |
| Large Context | 50,000 tokens | 5,000 tokens | 90% |
Speed Improvements
- Tool Selection: 50% faster with semantic routing
- Context Processing: 70% reduction in processing time
- Overall Latency: 30-50% improvement
- Cache Hit Rate: > 80% for common queries
🔧 Advanced usage
- Per-server forwarding:
POST /proxy/:serverNamewith a JSON-RPC body forwards to the upstream server named inconfig/default.json(mcpServers[].name). - Optimization API:
POST /optimize(public) orPOST /api/optimize(dashboard auth if configured) with{ "query": "...", "tools": [ ... ] }. - Library imports: the package is primarily distributed as a CLI; there is no stable
SmartProxy/createProxyexport in the published build—run vianode dist/index.jsor themcp-smart-proxybinary afternpm run build.
🧪 Testing```bash
npm test
npm run test:coverage
**Manual smoke tests** (proxy must be running):```bash
# No upstream MCP (only /health + /optimize)
node dist/index.js start --config ./config/local-smoke.json --port 3456
SMOKE_BASE_URL=http://127.0.0.1:3456 node scripts/smoke-http.mjs
# With upstream (enable server(s) in config/default.json, e.g. data.gouv)
node dist/index.js start --config ./config/default.json
node scripts/smoke-mcp-http.mjs
🔍 How it works
Semantic analysis (embeddings) → intelligent routing to MCP servers → context optimization (dedup, token-efficient format) → optional learning from query patterns.
📊 Monitoring
Dashboard at http://localhost:3000/dashboard. Metrics: curl http://localhost:3000/metrics (Prometheus: /metrics/prometheus, JSON: /analytics/json). Tracked: token savings, response time, cache hit rate, tool usage, error rates.
🔄 Maintenance
Regular Maintenance Tasks```bash
Run maintenance
npm run maintenance
Or via CLI
mcp-smart-proxy maintenance --optimize --cleanup
### Automated Maintenance```bash
# Set up cron job for daily maintenance
0 2 * * * cd /path/to/mcp-smart-proxy && npm run maintenance
🚨 Troubleshooting
Common Issues
"Proxy not connecting to MCP servers"```bash
curl http://localhost:3000/health
Ensure each **`mcpServers[].url`** is reachable (`https://…/mcp`), **`enabled`** is `true`, and the proxy was restarted after editing `config/default.json`.
#### "Slow performance"```bash
# Clear cache
mcp-smart-proxy maintenance --clear-cache
# Reduce optimization complexity
export MCP_OPTIMIZATION_LEVEL=basic
"High memory usage"```bash
Limit vector memory size
export MCP_VECTOR_MEMORY_MAX_SIZE=1000
Disable unused features
export MCP_SEMANTIC_ROUTING=false
### Debug Mode```bash
# Enable debug logging
DEBUG=mcp-smart-proxy:* npm start
# Or set environment variable
export MCP_DEBUG=true
🔮 Roadmap
Planned Features
- [ ] Advanced ML Models: Better semantic understanding
- [ ] Distributed Processing: Scale across multiple nodes
- [ ] Plugin System: Custom optimizations and integrations
- [ ] Real-time Dashboard: Live monitoring and control
- [ ] API Gateway: REST API for programmatic access
- [ ] Multi-protocol Support: Beyond MCP compatibility
In Progress
- [x] Core Proxy: Basic routing and optimization
- [x] Vector Memory: Semantic search and context selection
- [x] Performance Monitoring: Metrics and analytics
- [x] Documentation: Comprehensive guides and examples
🤝 Contributing
We welcome contributions from the community! Here's how to get started:
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
npm test - Submit a pull request
Development setup```bash
git clone https://github.com/Mourad95/mcp-smart-proxy.git && cd mcp-smart-proxy
make install && make build && make test
### Code Standards
- Follow TypeScript best practices
- Add tests for new features
- Update documentation
- Keep dependencies minimal
## 📚 Documentation
- Getting Started - First-time setup guide
- API Reference - Complete API documentation
- Advanced Usage - Custom configurations
- Semantic Cache - Semantic cache (similarity-based response caching)
- Performance Tuning - Optimization guide
- Troubleshooting - Common issues and solutions
- **SECURITY.md** - Security, privacy, local deployment
## 🐳 Production deployment
Production Docker setup: multi-stage Dockerfile, Docker Compose with sidecar MCP servers, health checks, persistent volumes (vector data), optional Prometheus + Grafana. See DEPLOYMENT.md for the full guide.
## 📄 License
MIT License - see LICENSE file for details.
## 🙏 Acknowledgments
- **Anthropic** for creating the Model Context Protocol
- **Cloudflare** for highlighting the context waste problem
- **OpenClaw Community** for inspiration and testing
- **All Contributors** for making this project better
## 🔗 Links
- **GitHub**: https://github.com/openclaw-community/mcp-smart-proxy
- **Documentation**: https://mcp-smart-proxy.openclaw.ai
- **Discord Community**: https://discord.com/invite/clawd
- **Issue Tracker**: https://github.com/openclaw-community/mcp-smart-proxy/issues
---
**Start optimizing your MCP usage today!** 🚀```bash
npm install mcp-smart-proxy
Fewer tokens, focused context, local-only — no data leakage. While Cloudflare shows MCP wastes 81% of context, we save up to 90%.
