mcp-slim-proxy
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
@pie527645-cloud/mcp-slim-proxy
Zero-bloat Model Context Protocol (MCP) multiplexer, lazy BM25 tool search engine, out-of-context multi-step pipeline runner, and linear-time tool-poisoning firewall.
Why MCP Slim Proxy?
Connecting an AI coding agent or desktop assistant to 4–8 standard MCP servers routinely injects 15,000 to 60,000+ tokens of raw JSON tool schemas into every single conversation turn—even when 95% of those tools are never called. Worse, untrusted or compromised community MCP servers can embed hidden prompt-injection payloads inside tool descriptions and property schemas (tool poisoning and cross-tool shadowing) that execute silently as soon as tools/list is loaded into the model prompt.
@pie527645-cloud/mcp-slim-proxy sits between your MCP host and any number of downstream stdio MCP servers:
Constant ~730-Token Context Footprint: Replaces dozens or hundreds of bloated downstream tool definitions with 4 compact meta-tools (
search_tools,describe_tool,invoke_tool,run_pipeline), cutting per-turn schema token overhead by 80%–98%.Built-in Tool-Poisoning Firewall (Quarantine ON by Default): Linearly scans every downstream tool's name, description, annotations, and nested JSON Schema strings before indexing. High- and critical-severity poisoned tools are automatically quarantined so neither their descriptions nor their execution paths are exposed to the model.
Lazy On-Demand Schema Loading:
search_toolsuses Okapi BM25 ranking overserver.toolName, parameter names, and 1-line summaries—returning zero full schemas until the agent callsdescribe_toolfor the specific tool it intends to invoke.Out-of-Context Sequential Pipelines:
run_pipelinechains1..10downstream tool calls directly inside the proxy process using${steps.0.text}and${steps.0.json.path.to.value}placeholders, keeping multi-kilobyte intermediate JSON responses out of the LLM context window.Cross-Platform Process-Tree Hygiene: Spawns downstream servers strictly with
shell: falseand cleanly reaps both child and grandchild processes on shutdown or request timeout across Windows (taskkill /T /F) and POSIX (-pgidprocess groups).
Related MCP server: mcp-toolmux
Architecture
flowchart LR
Host["MCP Client / Host"] <-->|"4 Lean Meta-Tools (~730 tokens)"| Proxy["mcp-slim-proxy (Stdio Server)"]
subgraph ProxyInternals["Proxy Core"]
direction TB
FW["Linear Poisoning Firewall (Quarantine ON)"]
BM25["BM25 Healthy Tool Index"]
PIPE["Out-of-Context Pipeline Engine"]
MGR["Downstream Manager (shell: false + Tree Reaper)"]
FW --> BM25
BM25 --> PIPE
PIPE --> MGR
end
Proxy --> ProxyInternals
MGR <-->|"stdio JSON-RPC"| S1["Downstream MCP Server A"]
MGR <-->|"stdio JSON-RPC"| S2["Downstream MCP Server B"]
MGR <-->|"stdio JSON-RPC"| S3["Downstream MCP Server C"]Requirements
Node.js:
>= 20.18.1(tested in CI across Node20.xand22.xon Ubuntu and Windows)npm:
>= 9.x
Installation (From Source)
Clone the repository, install dependencies, and compile the TypeScript source:
git clone https://github.com/pie527645-cloud/mcp-slim-proxy.git
cd mcp-slim-proxy
npm install
npm run buildVerify the build and test suite locally:
npm run lint
npm testConfiguration (slim-config.json)
Create a JSON configuration file listing the downstream stdio MCP servers you want to multiplex. The format matches the standard mcpServers block used by MCP hosts:
{
"mcpServers": {
"filesystem": {
"command": "node",
"args": ["/abs/path/to/filesystem-mcp/dist/index.js", "/abs/path/to/workspace"]
},
"git": {
"command": "node",
"args": ["/abs/path/to/git-mcp/dist/index.js"],
"cwd": "/abs/path/to/workspace",
"env": {
"GIT_OPTIONAL_LOCKS": "0"
}
}
}
}Configuration Rules
Server keys under
mcpServersmust be non-empty, must not contain.(dots separateserverName.toolNameintoolId), and cannot use reserved prototype keys (__proto__,constructor,prototype).Every server is spawned directly via
child_process.spawn(command, args, { shell: false }). Pass an executable binary path or runtime (node,python, etc.) ascommand.Provide the config path via
--config /abs/path/to/slim-config.jsonor theMCP_SLIM_CONFIGenvironment variable.
Connecting Your MCP Host
Point your MCP client (Claude Desktop, Cursor, Windsurf, VS Code MCP, etc.) to the compiled dist/mcp.js entrypoint:
{
"mcpServers": {
"slim-proxy": {
"command": "node",
"args": [
"/abs/path/to/mcp-slim-proxy/dist/mcp.js",
"--config",
"/abs/path/to/slim-config.json",
"--timeout",
"30000"
]
}
}
}Alternatively, configure the path using MCP_SLIM_CONFIG:
{
"mcpServers": {
"slim-proxy": {
"command": "node",
"args": ["/abs/path/to/mcp-slim-proxy/dist/mcp.js"],
"env": {
"MCP_SLIM_CONFIG": "/abs/path/to/slim-config.json"
}
}
}
}CLI Usage
The compiled CLI at dist/cli.js supports two subcommands: serve and savings.
1. Measure Token Savings & Audit Downstream Tools (savings)
Connects to every configured server, runs the full MCP initialize and tools/list handshake, scans all tool definitions through the poisoning firewall, prints the token savings and quarantine report, and reaps all downstream child processes cleanly:
node /abs/path/to/mcp-slim-proxy/dist/cli.js savings --config /abs/path/to/slim-config.jsonExample pretty output:
MCP Slim Proxy - Context Token Savings & Firewall Audit
========================================================
Firewall Quarantine : ENABLED (default)
Downstream Servers : 2
Discovered Tools : 18 total (13 healthy, 5 quarantined)
Per-Server Breakdown:
- commerce: 12 tools (12 healthy, 0 quarantined) | 6723 bytes (~1684 tokens)
- external: 6 tools (1 healthy, 5 quarantined) | 1719 bytes (~432 tokens)
Token Footprint Comparison:
Raw Tool Schemas : 2116 tokens (8442 bytes across 18 tools)
Proxied Meta-Tools : 739 tokens (2954 bytes across 4 tools)
Net Savings : 1377 tokens (65.08% saved per turn)For CI pipelines and automated scripts, output structured JSON via --format json (or --json):
node /abs/path/to/mcp-slim-proxy/dist/cli.js savings --config /abs/path/to/slim-config.json --format json2. Run the Multiplexer Stdio Server (serve)
node /abs/path/to/mcp-slim-proxy/dist/cli.js serve --config /abs/path/to/slim-config.json --timeout 30000CLI Flags
Flag | Default | Description |
|
| Path to JSON configuration file defining |
| Quarantine enabled | Disable automatic quarantine of high/critical poisoned tools (detection counts are still reported in |
|
| Per-request timeout in milliseconds ( |
|
| Output format for the |
| — | Print usage information and exit. |
| — | Print package version and exit. |
Exposed Meta-Tools (4 Total)
1. search_tools
Searches healthy (non-quarantined) downstream tools using Okapi BM25 keyword scoring over server.toolName, camelCase/snake_case tokens, parameter names, and 1-line summaries. Returns compact summaries with zero full JSON schemas.
Inputs:
query(string, required): Keywords to rank against, or*/""to list healthy tools alphabetically.server(string, optional): Filter results to a single configured server name.limit(integer, optional,1..50, default10): Maximum results to return.
2. describe_tool
Lazily fetches the complete description and full JSON inputSchema for one healthy tool right before invocation. Rejects unknown or quarantined tools with an explicit error.
Inputs:
toolId(string, required): Fully qualifiedserver.toolNameidentifier returned bysearch_tools.
3. invoke_tool
Forwards a single tools/call invocation to the owning downstream server within the configured --timeout. Rejects unknown or quarantined tools. If a downstream server hangs past --timeout, its entire process tree is terminated and lazily re-initialized on subsequent healthy requests.
Inputs:
toolId(string, required): Fully qualifiedserver.toolNameidentifier.arguments(object, optional): JSON arguments matching the downstream tool'sinputSchema.
4. run_pipeline
Executes 1..10 sequential downstream tool calls inside the proxy process without round-tripping intermediate outputs through the LLM context window.
Inputs:
steps(arrayof1..10objects):id(string, optional): Step alias for readable downstream references.toolId(string, required): Fully qualifiedserver.toolName.arguments(object, optional): JSON arguments supporting step output placeholders:${steps.<idx>.text}or${steps.<stepId>.text}— Raw text output of a prior step.${steps.<idx>.json.<dot.path>}or${steps.<stepId>.json.<dot.path>}— Extracted property or array index from a prior step's parsed JSON output. When a placeholder occupies the entire string value (for example"${steps.0.json.discountPct}"), its native JSON type (number,boolean,array,object) is preserved.
Example run_pipeline payload:
{
"steps": [
{
"id": "order",
"toolId": "commerce.fetch_order",
"arguments": { "orderId": "ORD-5500" }
},
{
"id": "customer",
"toolId": "commerce.fetch_customer",
"arguments": { "customerId": "${steps.0.json.customer.id}" }
},
{
"toolId": "commerce.format_invoice",
"arguments": {
"orderId": "${steps.order.json.orderId}",
"customerId": "${steps.0.json.customer.id}",
"region": "${steps.customer.json.region}",
"discountPct": "${steps.1.json.discountPct}",
"firstSku": "${steps.0.json.items.0.sku}"
}
}
]
}Security & Tool-Poisoning Firewall
All firewall checks use deterministic linear-time (O(n)) scanners with zero backtracking regular expressions:
Category | Severity | What Is Scanned & Blocked |
Hidden Unicode & BiDi |
| Zero-width characters ( |
HTML Comments |
| Closed ( |
Instruction Overrides |
| Override directives including |
Sensitive Exfiltration Targets |
| References to credential and secret paths including |
Cross-Tool Shadowing |
| Coercive behavioral hijacking directives ( |
Oversized / Deep Schema Guard ( |
| Fails closed when a tool schema exceeds |
Prototype-Pollution Guard | Runtime Error | Blocks |
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Single-connection meta-router indexing 500+ MCP servers & A2A tools with 85% token compression and
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceConsolidates multiple upstream MCP servers behind a single STDIO interface, exposing search_tools and run_tool to avoid context bloat.380 npm20MIT- AlicenseNot gradedqualityDmaintenanceProxy-style MCP tool multiplexer that aggregates multiple downstream stdio MCP servers into one, offering meta-tools for status, search, call, parallel, batch, and pipeline operations with concurrency control and caching.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI tools to uniformly discover, inspect, and call tools, prompts, and resources from multiple upstream MCP servers through a small set of fixed MCP tools, over stdio or HTTP.2MIT
- AlicenseNot gradedqualityBmaintenanceAggregates multiple MCP sub-servers into a single unified entry point, supporting stdio and Streamable HTTP protocols, with a web-based management interface for configuration, routing, and tool management.20 npm1MIT