mcp-mesh is a lazy MCP gateway that lets you discover, inspect, and invoke tools across multiple upstream MCP servers through four meta-tools.
Search aggregated upstream tools by natural language, optionally filtered by server and result limit.
Describe a specific tool’s full JSON schema and parameter specifications before invoking it.
Invoke any downstream tool by server ID, tool name, and arguments.
Check gateway status, connected servers, indexed tool count, and estimated token savings.
Federate heterogeneous MCP servers behind one endpoint, with schema minification, predictive pre-warming, circuit breakers, and telemetry as supporting features.
Aggregates a GitHub MCP server, exposing GitHub repository, issue, and pull request tools through mcp-mesh's lazy tool routing gateway.
Aggregates a PostgreSQL MCP server, enabling database query and management tools to be discovered and invoked through the gateway.
Aggregates a Slack MCP server, making Slack-related tools available alongside other upstream MCP services through the gateway.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-mesh search for a tool to query my Postgres database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-meshDynamic Model Context Protocol Gateway & Lazy Tool Router
Aggregates heterogeneous upstream MCP servers, indexes schemas into an inverted keyword search tree, and resolves parameter definitions on demand. Slashes Turn-0 context prompt bloat by 85–95% across 50+ tools with zero external dependencies.
Run the interactive demonstration immediately without installing any packages or setting up external servers:
# Run interactive enterprise demonstration (simulates 50 tools across 6 mock MCP servers)
uvx --from git+https://github.com/VanSchulist/mcp-mesh mcp-mesh --demo
# Or federate all workstation MCP servers across Claude, Cursor, and Antigravity into a single stdio pipe
uvx --from git+https://github.com/VanSchulist/mcp-mesh mcp-mesh run --federateRelated MCP server: MCP Gateway
The Model Context Protocol (MCP) standardizes how Large Language Models discover and invoke local/remote tools. However, in multi-server enterprise agent configurations (e.g. GitHub + PostgreSQL + Slack + AWS + Filesystem + Stripe), standard client implementations inject every tool's complete JSON Schema directly into the system prompt at Turn 0.
This creates three measurable architectural bottlenecks:
Turn-0 Token Bloat: Connecting to 6 production MCP servers (60 tools) consumes 9,790 to 32,450 tokens before the user submits an initial query.
Context Window Attention Degradation ("Lost in the Middle"): Flooding model attention heads with 50+ parameter schemas degrades tool selection accuracy and increases argument hallucination rates by 4–8%.
Pre-Fill Latency (TTFT): Processing 10k–30k prompt tokens adds 400ms to 1,300ms of pre-fill latency to every agent turn.
mcp-mesh resolves this by operating as a local JSON-RPC 2.0 reverse proxy. Instead of exposing dozens of static tool definitions, it exposes 4 lightweight meta-tools (mesh_search_tools, mesh_describe_tool, mesh_invoke_tool, mesh_status). Upstream schemas are indexed in memory and retrieved lazily on demand.
Data collected from mcp-mesh-eval empirical simulation suite running 60 enterprise MCP tools across frontier model pricing profiles:
Metric | Raw MCP Baseline | mcp-mesh Gateway | Delta |
Turn-0 Prompt Footprint | 9,790 tokens | 527 tokens | -94.6% |
Active Schemas in Context | 60 full JSON schemas | 4 meta-tools | -56 schemas filtered |
Projected TTFT (GPT-6 Astra) | 1,152.2 ms | 364.8 ms | -68.3% (-787.4ms) |
Projected TTFT (Claude Sonnet 5.5) | 601.2 ms | 212.1 ms | -64.7% (-389.1ms) |
Projected TTFT (Gemini 3.8 Flash) | 271.2 ms | 104.5 ms | -61.5% (-166.7ms) |
Process Resident Set Size (RSS) | N/A (10 unmanaged procs) | 16.4 MB idle / 24.8 MB peak | Deterministic memory bounds |
Pipeline Stage | P50 Latency | P95 Latency | P99 Latency | Implementation Mechanism |
Inverted Index Keyword Search | 0.8 ms | 1.1 ms | 1.4 ms | Pure Python inverted index + tokenized BM25-style scoring |
Predictive Process Pre-Warming | 0.9 ms | 1.4 ms | 1.8 ms | Background daemon thread spawning stdio pipes upon search |
LRU Hot-Tier Schema Cache Hit | 0.2 ms | 0.3 ms | 0.4 ms | In-memory OrderedDict dictionary lookup |
Subprocess IPC Dispatch & Proxy | 2.3 ms | 2.8 ms | 3.2 ms | Non-blocking |
$$\Delta T = \sum_{i=1}^{N} T_{\text{raw}}(i) - \left( T_{\text{meta}} + \sum_{k=1}^{M} T_{\text{resolved}}(k) \right)$$
Where $N=60$ total tools, $T_{\text{meta}} = 527$ tokens, and $M=2$ tools actually utilized by the agent during a multi-turn task: $$\Delta T = 9,790 - (527 + 240) = 9,023 \text{ tokens saved per turn } (92.2% \text{ net reduction})$$
mcp-mesh (Trade-offs & Limitations)Engineering integrity requires stating where an architectural pattern is inappropriate. mcp-mesh is not a silver bullet for every agent configuration:
Small Toolsets ($\le 3 \sim 5$ Tools):
Trade-off: When an agent only connects to 1 or 2 lightweight servers (e.g. a local filesystem server with 3 tools), total Turn-0 prompt overhead is under 500 tokens.
Limitation: Introducing a reverse proxy layer adds ~0.8ms IPC latency and an extra indirection hop. In this regime, static schema injection is simpler and faster.
Single-Turn Bulk Tool Invocations:
Trade-off: If an agent's workflow deterministically requires invoking 80%+ of all registered tools in every single turn, dynamic lazy loading introduces unnecessary discovery roundtrips.
Limitation: Static schema injection avoids the two-stage lookup overhead when tool diversity per turn approaches 100%.
Two-Stage Round-Trip Time (RTT) Overhead:
Trade-off: Lazy resolution requires the LLM to call mesh_search_tools first, inspect the compact signature, and then invoke mesh_invoke_tool.
Limitation: While predictive pre-warming eliminates child process spawn latency, this workflow consumes 1 additional LLM inference turn if the model has not previously cached the tool signature in its conversational history.
Severe Memory Limits on Constrained Edge Devices:
Trade-off: When federating 10 separate upstream servers, mcp-mesh supervises 10 child OS processes (consuming ~12–15MB RSS each, totaling ~120–150MB RAM).
Limitation: On severely constrained edge devices ($< 256\text{MB}$ RAM), hosting tools in a single monolithic Python process is preferable to multi-process process isolation.
┌────────────────────────────────────────────────────────────────────────┐
│ Heterogeneous AI Clients / IDEs │
│ Claude Desktop │ Cursor │ Google Antigravity │
└───────────────────────────────────┬────────────────────────────────────┘
│ stdio (JSON-RPC 2.0)
│ 4 Active Meta-Tools (~527 tokens)
▼
┌────────────────────────────────────────────────────────────────────────┐
│ mcp-mesh v1.4 Federation Gateway │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Federation Manager (Auto-discovery, Loop Prevention) │ │
│ ├──────────────────────────────────────────────────────────────────┤ │
│ │ Tool Indexer, BM25 Scoring & Predictive Pre-Warmer │ │
│ ├──────────────────────────────────────────────────────────────────┤ │
│ │ Circuit Breakers, Telemetry Ledger & Transparent Process Router │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────┬────────────────────────────────────┘
│ Supervised upstream stdio pipes
┌───────────────────────────┼───────────────────────────┐
▼ ▼ ▼
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│ github MCP │ │ postgres MCP │ │ filesystem MCP │
│ [Circuit: CLOSED] │ │ [Circuit: CLOSED] │ │ [Circuit: CLOSED] │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘AST-Based Schema Minification (mcp_mesh.minifier): Analyzes and compresses JSON-Schema ASTs on the fly during mesh_describe_tool. Strips non-semantic metadata ($schema, title, redundant comments), prunes long natural language descriptions to concise parameter contracts, and hoists duplicate sub-schemas while strictly preserving validation constraints (type, enum, required, minimum/maximum). Slashes Turn-1 schema prompt consumption by 35–55%.
Zero External Dependencies: Pure Python 3.10+ standard library (concurrent.futures, json, sqlite3, http.server, subprocess, argparse, dataclasses). Runs instantly on any environment without pip install or native C-extension compilation.
Universal Heterogeneous Federation (--federate): Discovers and federates MCP configurations across Google Antigravity (~/.gemini/config/mcp_config.json), Claude Desktop (claude_desktop_config.json), and Cursor (~/.cursor/mcp.json) into a single unified endpoint with automatic circular-proxy prevention.
Predictive Background Pre-Warming: Spawns and handshakes upstream child processes concurrently in background threads the moment an agent searches for them (mesh_search_tools), hiding process boot latency.
Automated Circuit Breakers: Isolates crashing or hanging upstream servers. After 3 consecutive timeouts (default 10s), the gateway trips the circuit to OPEN, returning immediate error envelopes without blocking the host agent.
Persistent SQLite Telemetry Ledger: Complete local audit trail (~/.mcp-mesh/telemetry.db) recording microsecond latencies, token consumption baselines, and LRU cache hit ratios with SQL queryability (mcp-mesh stats --db / --sql).
Environment Health Diagnostics (mcp-mesh doctor): Inspects runtime dependencies (node, npx, uv, git, docker), configuration schema validity, and upstream executable reachability.
HTTP / Server-Sent Events Daemon (mcp-mesh sse): Exposes an authenticated streaming SSE endpoint for remote agents or containerized clusters.
Add mcp-mesh to your MCP client configuration (claude_desktop_config.json or mcp_config.json):
{
"mcpServers": {
"mcp-mesh": {
"command": "mcp-mesh",
"args": ["run", "--federate"]
}
}
}Or define upstream servers explicitly in mcp_mesh.json:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/prod"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
}
}
}# 1. Start gateway with universal auto-federation across all IDE configs
mcp-mesh run --federate
# 2. Run zero-config enterprise demonstration (50 tools across 6 mock servers)
mcp-mesh --demo
# 3. View aggregated token economy report
mcp-mesh stats --federate
# 4. Search indexed tools via natural language in terminal
mcp-mesh search "git pull request" --federate
# 5. Query persistent SQLite telemetry ledger
mcp-mesh stats --db
# 6. Run diagnostic health check on MCP environment
mcp-mesh doctor
# 7. Start HTTP/SSE streaming gateway daemon
mcp-mesh sse --port 8000
# 8. Inspect tool schema (AST-minified by default, with --stats or --raw)
mcp-mesh inspect github::create_issue --stats
mcp-mesh inspect github::create_issue --raw
# 9. Generate shell auto-completion scripts (Bash, Zsh, PowerShell)
mcp-mesh completion bash >> ~/.bashrc
mcp-mesh completion zsh > ~/.zfunc/_mcp-mesh
mcp-mesh completion powershell | Out-String | Invoke-ExpressionThe test suite validates JSON-RPC 2.0 protocol adherence, concurrency, schema minification, LRU caching, and circuit breaker trip logic:
python -m unittest discover -s tests -vAll 90 unit and integration tests execute in under 6 seconds on standard hardware using Python's built-in unittest harness.
Released under the MIT License. Maintained by Van Schulist (@VanSchulist) at Existential Cloud AI Studio.
Inspect the full JSON schema and detailed parameter specifications of a specific tool before invoking it.
| Name | Required | Description | Default |
|---|---|---|---|
| minify | No | Whether to return token-minified schema (prunes non-semantic keys & redundant descriptions). Default: true. | |
| server | Yes | The downstream server ID hosting the tool. | |
| tool_name | Yes | The target tool name to inspect. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. 'Inspect' implies a read-only, non-invoking operation, which is useful behavioral context, but the description does not explicitly state that the tool has no side effects, whether permissions are required, or how the default minification affects returned content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It states the action, the target, and the timing in one compact phrase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-oriented inspection tool with a fully documented schema and no output schema, the description covers what the tool does and when to use it. A minor gap is that it says 'full JSON schema' without acknowledging that the default minify=true may prune some non-semantic content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already well documented in the input schema. The description adds only the broad notion of inspecting a 'specific tool'; it does not add practical meaning beyond the schema for server, tool_name, or minify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: inspect the JSON schema and parameter specifications of a specific tool. It is clear, but it does not explicitly distinguish itself from all siblings such as mesh_search_tools or mesh_status; it only indirectly contrasts with mesh_invoke_tool via 'before invoking it.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before invoking it' gives a clear usage context: call this to inspect a tool prior to execution. It does not explicitly name alternatives or exclusions, such as when to search for tools first versus describing a known tool, so it falls short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Directly execute any tool on a downstream MCP server. Pass server ID, target tool name, and input arguments dictionary.
| Name | Required | Description | Default |
|---|---|---|---|
| server | No | The downstream server ID (e.g. 'github', 'postgres'). Optional if tool_name is namespaced as 'server::tool'. | |
| arguments | No | JSON arguments matching the tool's parameter schema. | |
| tool_name | Yes | The exact tool name to execute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure, and it does not say that this proxies arbitrary downstream operations that may be destructive, nor whether downstream auth/connection requirements must be met first. It also says nothing about how downstream errors or results are propagated back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core action front-loaded and no filler. The second sentence largely echoes the schema's parameter names, which is mild redundancy but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter proxy-execution tool with a nested arguments object, no annotations and no output schema, the definition leaves significant gaps: what the response looks like (the wrapped downstream result), how failures surface, and any precondition that the downstream server is reachable. The description is too thin given the complexity of what it does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters, including the 'server::tool' namespacing rule for `server`. The description only restates the parameter names ('server ID, target tool name, and input arguments dictionary') and adds no format or edge-case detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Directly execute') and resource ('any tool on a downstream MCP server'), which is enough for an agent to distinguish it from the read-only siblings mesh_describe_tool, mesh_search_tools and mesh_status. It stops short of explicitly naming those siblings as alternatives, so it sits at clear-but-not-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this versus mesh_describe_tool or mesh_search_tools, and no prerequisites are given (e.g. that the target tool's schema should be fetched first, or that the downstream server must be registered/available). The word 'Directly' hints at bypassing a higher-level flow but the reader must infer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for relevant tools across all aggregated MCP servers using natural language keywords (e.g. 'git commit', 'read file', 'query postgres'). Returns ultra-compact signatures and relevance scores.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum candidate tools to return (default: 5). | |
| query | Yes | Keywords or functional goal describing the desired tool. | |
| server | No | Optional downstream server ID to restrict search. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose scope and return shape ('across all aggregated MCP servers', 'ultra-compact signatures and relevance scores'). It omits any statement about cost, latency, result ranking behavior, or what happens with an empty/miss result, which an agent would want for a cross-server fan-out search.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, purpose front-loaded, examples parenthetically embedded without bloat. No filler, though the parenthetical examples are the only slight padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description rightly mentions the return format (signatures + relevance scores), and all three parameters are schema-documented. For a discovery tool with no annotations it is largely sufficient, missing only ranking/pagination behavior and explicit sibling routing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents query, limit and server. The keyword examples in the description add modest interpretive value for how to phrase 'query', but nothing beyond that; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb ('Search') and resource ('tools across all aggregated MCP servers') plus concrete keyword examples ('git commit', 'read file'). It clearly contrasts implicitly with mesh_invoke_tool/mesh_describe_tool by framing itself as discovery, but never names those siblings to make the distinction explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says how to search (natural language keywords) but not when to reach for this tool versus mesh_describe_tool, mesh_invoke_tool or mesh_status, and no workflow (search -> describe -> invoke) is suggested. Usage is only faintly implied by the tool's name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect real-time gateway statistics: connected downstream servers, total tools indexed, and estimated context token savings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the safety profile; 'inspect' reasonably implies a read-only, side-effect-free call, and 'real-time' is a useful disclosure about freshness. It does not state whether calling it consumes tokens, requires an active connection, or what happens if no servers are connected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with a colon-separated list of what is returned; no filler, no restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, zero-annotation read tool with no output schema, the description covers the essentials of what is returned. It is only slightly short of complete because it omits read-only confirmation and any failure/empty-state behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; the description correctly presents it as a no-argument call and spends its words on the returned data instead of inventing parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (inspect) and resource (real-time gateway statistics) and enumerates the three things returned: connected downstream servers, indexed tools, and token savings. That is far more specific than the siblings' search/describe/invoke surface, though it never names or contrasts them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this versus mesh_search_tools or mesh_describe_tool, nor any stated prerequisite (e.g., call before or after connecting servers). Usage is only implied by the word 'inspect'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.0mesh_describe_tool1 field changedInput schema / properties / minifyAdded value: +{
+ "default": true,
+ "description": "Whether to return token-minified schema (prunes non-semantic keys & redundant descriptions). Default: true.",
+ "type": "boolean"
+}mesh_invoke_tool2 fields changedInput schema / properties / server / descriptionPrevious value: -"The downstream server ID (e.g. 'github', 'postgres')."New value: +"The downstream server ID (e.g. 'github', 'postgres'). Optional if tool_name is namespaced as 'server::tool'."Input schema / requiredPrevious value: -[
- "server",
- "tool_name"
-]New value: +[
+ "tool_name"
+]v1.0.0mesh_describe_toolmesh_invoke_toolmesh_search_toolsmesh_statusScored across 4 tools
Each tool targets a distinct stage of the gateway workflow: search (discovery), describe (schema inspection), invoke (execution), and status (monitoring). There is no meaningful overlap, and boundaries are reinforced by clear verb choices.
All tools share a consistent 'mesh_' prefix with snake_case, and three follow a verb_noun pattern (describe_tool, invoke_tool, search_tools). mesh_status is a noun-style name, a minor deviation from the otherwise predictable convention.
Four tools is tightly scoped to the meta-server/gateway purpose: discover, inspect, invoke, and monitor. Each tool earns its place with no redundancy or filler.
The search -> describe -> invoke lifecycle is fully covered, with status for observability. Minor gaps exist, such as listing connected servers or refreshing the tool index explicitly, but agents can work around these via status and search.
Single-connection meta-router indexing 500+ MCP servers & A2A tools with 85% token compression and
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
