# Mcplex > MCPlex - The MCP Smart Gateway. Semantic tool routing, security guardrails, and real-time observability for AI agents. - **Type:** MCP server - **Install:** `agentstack add mcp-modernops888-mcplex` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [ModernOps888](https://agentstack.voostack.com/s/modernops888) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ModernOps888](https://github.com/ModernOps888) - **Source:** https://github.com/ModernOps888/mcplex ## Install ```sh agentstack add mcp-modernops888-mcplex ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # πŸš€ MCPlex β€” The MCP Smart Gateway **Semantic tool routing β€’ Security guardrails β€’ Real-time observability** [](https://github.com/ModernOps888/mcplex/actions/workflows/ci.yml) [](https://github.com/ModernOps888/mcplex/releases) [](LICENSE) [](https://www.rust-lang.org/) [](https://modelcontextprotocol.io) *Stop dumping 50k tokens of tool definitions into your LLM's context window.* *MCPlex intelligently routes only the tools your agent actually needs.* --- ## The Problem Every developer building multi-agent AI systems with MCP hits the same wall: | Pain Point | Impact | |-----------|--------| | 🧠 **Context Bloat** | 20+ MCP servers = 50k+ tokens of tool definitions consuming your context window | | πŸ”“ **No Security** | No RBAC, no audit trails, tool poisoning vulnerabilities | | πŸ‘οΈ **Blind Operations** | Can't track costs, latency, or debug wrong tool selection | | πŸ”„ **Restart Required** | Config changes require full restart in production | | πŸ•ΈοΈ **NΓ—M Complexity** | Orchestrating dozens of servers is an integration nightmare | ## The Solution MCPlex is a **single-binary Rust gateway** that sits between your AI agent and MCP servers: ``` Your Agent ──→ MCPlex Gateway ──→ GitHub MCP (stdio β€” persistent) β”‚ ──→ Slack MCP (stdio β€” persistent) β”‚ ──→ Database MCP (HTTP) β”‚ ──→ Filesystem MCP (stdio β€” persistent) β–Ό 🧠 Smart Routing (70-90% token savings) πŸ”’ RBAC + Audit Logs + API Key Auth πŸ“Š Real-time Dashboard + Prometheus πŸ“¦ Response Caching (auto-detect read-only) πŸ”‘ Multi-Tenant (API key β†’ role mapping) πŸ”₯ Hot-reload Config ``` ### Transport Support MCPlex supports **both** MCP transport types as a first-class citizen: | Transport | Discovery | Runtime Calls | Connection Model | |-----------|-----------|---------------|-----------------| | **Stdio** | βœ… Full MCP handshake | βœ… Multiplexed JSON-RPC | Persistent child process (long-lived) | | **Streamable HTTP** | βœ… Full MCP handshake | βœ… Standard HTTP POST | Stateless (connection pooling) | Stdio servers are spawned at startup and kept alive for the gateway's lifetime. The MCP handshake (`initialize` β†’ `notifications/initialized`) runs once, then all subsequent `tools/call`, `resources/read`, and `prompts/get` requests are multiplexed over the same stdin/stdout pipe using JSON-RPC ID correlation. ## ⚑ Quick Start ### 1. Install (Pre-built Binary) Download the latest release from [GitHub Releases](https://github.com/ModernOps888/mcplex/releases): ```bash # Linux / macOS curl -LO https://github.com/ModernOps888/mcplex/releases/latest/download/mcplex-linux-x86_64 chmod +x mcplex-linux-x86_64 sudo mv mcplex-linux-x86_64 /usr/local/bin/mcplex ``` ### 2. Build from Source ```bash git clone https://github.com/modernops888/mcplex.git cd mcplex cargo build --release ``` ### 3. Configure ```bash cp mcplex.toml my-config.toml # Edit my-config.toml with your MCP servers ``` **Minimal config for stdio servers:** ```toml [gateway] listen = "127.0.0.1:3100" dashboard = "127.0.0.1:9090" [router] strategy = "semantic" [[servers]] name = "filesystem" command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] [[servers]] name = "memory" command = "npx" args = ["-y", "@modelcontextprotocol/server-memory"] ``` ### 4. Run ```bash ./target/release/mcplex --config my-config.toml # Expected output: # πŸ”Œ Spawning stdio server 'filesystem': npx ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] # 🀝 MCP handshake complete for 'filesystem' # πŸ“‘ Server 'filesystem': 11 tools, 0 resources, 0 prompts # πŸ”Œ Spawning stdio server 'memory': npx ["-y", "@modelcontextprotocol/server-memory"] # 🀝 MCP handshake complete for 'memory' # πŸ“‘ Server 'memory': 3 tools, 0 resources, 0 prompts # ⚑ MCPlex gateway listening on 127.0.0.1:3100 ``` ### 5. Connect Your Agent Point your MCP client to `http://127.0.0.1:3100/mcp` and open the dashboard at `http://127.0.0.1:9090`. ## πŸš€ Running as a Service (Deployment) For persistent environments, run MCPlex as a background service to ensure it starts automatically on boot and restarts if it crashes. ### Linux (`systemd`) Create a systemd unit file at `/etc/systemd/system/mcplex.service`: ```ini [Unit] Description=MCPlex Gateway After=network.target [Service] Type=simple User=your_user WorkingDirectory=/path/to/mcplex ExecStart=/usr/local/bin/mcplex --config /path/to/mcplex/mcplex.toml Restart=always RestartSec=3 [Install] WantedBy=multi-user.target ``` Enable and start the service: ```bash sudo systemctl daemon-reload sudo systemctl enable mcplex sudo systemctl start mcplex sudo systemctl status mcplex ``` ### macOS (`launchd`) Create a launchd plist file at `~/Library/LaunchAgents/com.modernops.mcplex.plist`: ```xml Label com.modernops.mcplex ProgramArguments /usr/local/bin/mcplex --config /path/to/mcplex.toml RunAtLoad KeepAlive StandardOutPath /tmp/mcplex.log StandardErrorPath /tmp/mcplex-error.log EnvironmentVariables PATH /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin ``` Load and start the service: ```bash launchctl load ~/Library/LaunchAgents/com.modernops.mcplex.plist launchctl start com.modernops.mcplex ``` ### Log Rotation When running as a service, ensure you implement log rotation to prevent infinite log growth. For macOS, add an entry to `/etc/newsyslog.conf`; for Linux, use `logrotate`. MCPlex also has built-in audit log rotation configured via `max_log_size_mb`. ### Service Troubleshooting | Issue | Resolution | |-------|------------| | Service fails to start immediately | Check your configuration file syntax by running `mcplex --check --config ` manually. | | Port already in use | Verify no other service is bound to the `listen` port. Change `gateway.listen` in your config. | | `launchd` permission errors | Ensure the `ProgramArguments` path is absolute and executable by the user. | | Server respawn loop | Check the `StandardErrorPath` log for fatal bootstrap errors or missing dependencies (e.g., Node.js for `npx` servers). | --- ## πŸ”Œ How to Connect Your Agent MCPlex is a **transparent MCP proxy** β€” any MCP client that supports Streamable HTTP can connect to it. Your agent talks to MCPlex as if it were a single MCP server, and MCPlex handles multiplexing, routing, and security behind the scenes. ### Claude Code / Claude Desktop (Recommended β€” stdio bridge) Claude Code and Claude Desktop use **stdio transport**. MCPlex ships a cross-platform bridge (`bridge.mjs`) that translates stdio ↔ HTTP. Works on **macOS, Windows, and Linux**. Add a `.mcp.json` to your project root (Claude Code auto-discovers it): ```json { "mcpServers": { "mcplex": { "command": "node", "args": ["/path/to/mcplex/bridge.mjs"], "env": { "MCPLEX_GATEWAY": "http://127.0.0.1:3100/mcp" } } } } ``` For Claude Desktop, add the same config to `claude_desktop_config.json`. ### VS Code / GitHub Copilot (agent mode) VS Code supports MCP servers natively. Add a `.vscode/mcp.json` to your workspace (or run **MCP: Add Server** from the Command Palette) pointing at the MCPlex bridge: ```json { "servers": { "mcplex": { "type": "stdio", "command": "node", "args": ["/path/to/mcplex/bridge.mjs"], "env": { "MCPLEX_GATEWAY": "http://127.0.0.1:3100/mcp" } } } } ``` A ready-to-copy template lives at [examples/vscode-mcp.json](examples/vscode-mcp.json). With the default **meta-tool mode**, Copilot's agent sees just 3 gateway tools (~200 tokens) instead of every tool definition from every connected server β€” the same 70–90% context savings apply inside your IDE session. Tool discovery happens on demand via `mcplex_find_tools`, and every call is still routed through RBAC, allowlists, audit logging, and the response cache. ### Cursor / Windsurf / HTTP-capable MCP Clients Clients that support streamable HTTP can connect directly: ```json { "mcpServers": { "mcplex-gateway": { "url": "http://127.0.0.1:3100/mcp" } } } ``` ### Custom Python Agent ```python import requests GATEWAY = "http://127.0.0.1:3100/mcp" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} # Optional # Initialize resp = requests.post(GATEWAY, json={ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "my-agent", "version": "1.0"}} }, headers=HEADERS) # List all tools (MCPlex aggregates from all servers) resp = requests.post(GATEWAY, json={ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }, headers=HEADERS) tools = resp.json()["result"]["tools"] # Call a tool (MCPlex routes to the right server automatically) resp = requests.post(GATEWAY, json={ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "create_issue", "arguments": {"repo": "my-repo", "title": "Bug fix"}} }, headers=HEADERS) ``` ### How It Catches Your Agent's Calls MCPlex acts as a **man-in-the-middle proxy** for all MCP traffic: ``` Your Agent ──POST /mcp──→ MCPlex Gateway ──→ Upstream MCP Server β”‚ (persistent stdio or HTTP) β”œβ”€ βœ… Auth check (constant-time API key compare) β”œβ”€ 🚦 Rate limit check β”œβ”€ πŸ§ͺ Input validation (name charset, 64KB / depth-16 args cap) β”œβ”€ πŸ”’ RBAC + allowlist/blocklist (role bound to API key) β”œβ”€ πŸ“ Audit log (every call) └─ πŸ“Š Metrics (latency, tokens, security events) ``` Every `tools/call` goes through the security engine and is logged. Every `tools/list` goes through the semantic router. There's no way to bypass it β€” if your agent uses MCPlex as its MCP endpoint, **all calls are intercepted, checked, and logged**. ## πŸ€– Compatible AI Models MCPlex is model-agnostic β€” it routes any MCP-compliant client traffic regardless of which LLM is driving it. These are the frontier models actively tested with MCPlex as of July 2026: | Model | Provider | MCP Client | Best For | |-------|----------|-----------|----------| | **GPT-5.6 Sol** | OpenAI | ChatGPT Work, custom | Flagship reasoning + agentic tasks | | **GPT-5.6 Terra** | OpenAI | ChatGPT Work, custom | Balanced performance / cost | | **GPT-5.6 Luna** | OpenAI | ChatGPT Work, custom | Cost-efficient everyday tasks | | **Claude Fable 5** | Anthropic | Claude Code, Claude Desktop | Extended reasoning + code | | **Claude Mythos 5** | Anthropic | Claude Code, Claude Desktop | Complex multi-step agent workflows | | **Claude Sonnet 5** | Anthropic | Claude Code, Claude Desktop | High-capability, broad availability | | **Gemini 3.5 Flash** | Google | Gemini Spark, custom | High-throughput, cost-efficient | | **Gemini 3.1 Pro** | Google | Gemini Spark, custom | Multimodal + Workspace integration | | **Grok 4.5** | xAI | Custom / open-weight stacks | Competitive reasoning, open ecosystem | The meta-tool pattern (3 gateway tools, ~200 tokens) is particularly effective with models that have smaller default context budgets β€” MCPlex's token savings become more impactful as model costs rise. > **Context savings scale with model pricing.** With GPT-5.6 Sol at frontier pricing, eliminating 40k tokens of tool definitions per request translates to measurable cost reduction at scale. ## 🧠 Semantic Tool Routing The killer feature. Instead of dumping all tool definitions into your LLM's context, MCPlex uses a **meta-tool pattern** that works with **every standard MCP client** β€” no custom extensions needed: | Scenario | Without MCPlex | With MCPlex | Savings | |----------|---------------|-------------|---------| | 5 servers, 50 tools | ~10,000 tokens | ~200 tokens | **98%** | | 10 servers, 100 tools | ~20,000 tokens | ~200 tokens | **99%** | | 20 servers, 200 tools | ~40,000 tokens | ~200 tokens | **99.5%** | ### How It Works When your agent calls `tools/list`, MCPlex returns **3 lightweight meta-tools** (~200 tokens) instead of all real tools: ``` Agent MCPlex Gateway β”‚ β”‚ β”œβ”€β”€tools/list──────────────────►│ Returns: mcplex_find_tools, mcplex_call_tool, β”‚ β”‚ mcplex_list_categories (~200 tokens) β”‚ β”‚ β”œβ”€β”€mcplex_find_tools────────────►│ "store a memory" │◄─────────────────────────────── β†’ [{name: "create_memory", desc: "...", inputSchema: {...}}, β”‚ β”‚ {name: "save_note", desc: "...", inputSchema: {...}}] β”‚ β”‚ β”œβ”€β”€mcplex_call_tool─────────────►│ {name: "create_memory", arguments: {...}} │◄─────────────────────────────── β†’ tool result (routed through security + cache + audit) ``` - **`mcplex_find_tools(query)`** β€” Search for tools by natural language intent. Returns matching tools with full schemas. - **`mcplex_call_tool(name, arguments)`** β€” Execute a discovered tool. Routes through the full security/audit/cache pipeline. - **`mcplex_list_categories()`** β€” Browse available tool categories (server groups) with tool counts. This works with Claude Code, Claude Desktop, Cursor, Windsurf, and any other MCP client β€” no custom extensions or client-side plugins required. ### Routing Mode MCPlex supports three routing modes via `router.mode`: | Mode | Behavior | Client Compatibility | |------|----------|---------------------| | **`metatool`** (default) | Returns 3 gateway meta-tools; agent discovers real tools via `mcplex_find_tools` | βœ… All standard MCP clients | | **`passthrough`** | Returns all real tools directly (no routing indirection) | βœ… All standard MCP clients | | **`legacy`** | Uses `_mcplex_query` param extension for filtering | ❌ Custom clients only | ### Routing Strategy Within `metatool` and `legacy` modes, MCPlex uses a routing strategy to rank tools: - **`semantic`** β€” Character n-gram embeddings with cosine similarity (recommended) - **`keyword`** β€” TF-IDF keyword matching (zero ML dependency) - **`passthrough`** β€” No filtering (baseline) ```toml [router] mode = "metatool" # "metatool", "passthrough", or "legacy" strategy = "semantic" # "semantic", "keyword", or "passthrough" top_k = 5 # Return top 5 most relevant tools similarity_threshold = 0.3 # Minimum relevance score cache_embeddings = true # Cache for faster repeated queries ``` ## πŸ”’ Security Engine ### Role-Based Access Control (RBAC) ```toml [security] enable_rbac = true [roles.developer] allowed_tools = ["github/*", "database/query_*"] [roles.admin] allowed_tools = ["*"] [roles.readonly] allowed_tools = ["*/list_*", "*/get_*"] blocked_tools = ["*/delete_*", "*/drop_*"] ``` > **Role trust boundary:** a caller's role is only ever established server-side, from a verified `api_key`/`api_keys` match β€” never from anything a client sends in the request body. When `enable_rbac = true` and no `api_key`/`api_keys` are configured, every tool call is denied by default (no role can be established), and the gateway logs a startup warning so this isn't mistaken for a bug. ### Per-Server Tool Blocklists ```toml [[servers]] name = "database" url = "http://localhost:8080/mcp" blocked_tools = ["drop_table", "delete_*", "truncate_*"] ``` ### Structured Audit Logging Every tool invocation is logged as JSON Lines: ```json {"timestamp":"2026-04-10T10:00:00Z","event":"tool_call","tool_name":"github/create_issue","server_name":"github","duration_ms":342,"trace_id":"a1b2c3d4"} {"timestamp":"2026-04-10T10:00:01Z","event":"tool_blocked","tool_name":"database/drop_table","reason":"security_policy","trace_id":"e5f6g7h8"} ``` ## πŸ“Š … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [ModernOps888](https://github.com/ModernOps888) - **Source:** [ModernOps888/mcplex](https://github.com/ModernOps888/mcplex) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-modernops888-mcplex - Seller: https://agentstack.voostack.com/s/modernops888 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.