Skip to main content
Glama
deenesjakoruzh
itsPremkumar

mcp-agent-mesh

by itsPremkumar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

mcp-agent-mesh

A mesh gateway for MCP — lets one MCP client reach N MCP servers with prefix-based routing, health checks, circuit-breaker failover, and a unified endpoint over both stdio and Streamable HTTP.

What it does

mcp-agent-mesh aggregates multiple upstream MCP servers behind a single logical MCP server. Every upstream tool is exposed under a server_name.tool_name prefix, so a client connecting to the mesh sees a single tools/list containing tools from all healthy upstreams.

When a tool call fails and the server's circuit breaker opens, the mesh automatically fails over to configured replica servers before returning an error to the client.

Related MCP server: mcp-0ne

Features

Feature

Description

Aggregation

tools/list merges every upstream server's tools into one flat list

Prefix routing

Call math.add and the mesh routes to the math server

Circuit breaker

Per-server circuit breaker with configurable threshold & timeout

Health polling

Background ping loop detects early upstream failures

Failover

Configurable failover groups let aliases take over for a failing server

Dual transport

Runs as a stdio MCP server and a Streamable HTTP server

Timeouts + retries

Every upstream call is wrapped in asyncio.wait_for

Architecture

                     ┌─────────────────────┐
  MCP client ───────►│   MeshGateway       │
                     │   (stdio / HTTP)    │
                     └────────┬───────────┘
                              │ tools/list
                              │ tools/call
                    ┌─────────┼─────────────┐
                    ▼         ▼             ▼
               ┌────────┐ ┌─────────┐ ┌─────────┐
               │ Server │ │ Server  │ │ Server  │
               │  "A"   │ │  "B"   │ │  "C"   │   (upstream MCP servers)
               └────────┘ └─────────┘ └─────────┘

Modules

Module

Responsibility

config.py

YAML config parsing — ServerConfig, MeshConfig

health.py

Per-server CircuitBreaker + ServerHealthMonitor (background ping)

router.py

Prefix routing (server.tool), failover group resolution, tool registry

gateway.py

MeshGateway — connects to upstreams, aggregates tool listings, routes calls, serves MCP over stdio + HTTP

Installation

pip install -e ".[dev]"

Usage

CLI (stdio mode)

mcp-agent-mesh --config examples/mesh.yaml --transport stdio

HTTP mode

mcp-agent-mesh --config examples/mesh.yaml --transport http --host 0.0.0.0 --port 8000

As a client config (Claude Code / Codex / OpenCode)

{
  "mcpServers": {
    "mesh": {
      "command": "mcp-agent-mesh",
      "args": ["--config", "/path/to/mesh.yaml", "--transport", "stdio"]
    }
  }
}
{
  "mcpServers": {
    "mesh": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Configuration

See examples/mesh.yaml for a full example. Key fields:

servers:
  - name: math            # tool-name prefix
    transport: stdio       # "stdio" or "http"
    command: python        # stdio: how to spawn
    args: ["-m", "..."]
    url: http://...        # http: endpoint URL
    timeout: 30.0
    circuit_breaker_threshold: 3
    circuit_breaker_timeout: 300.0

failover_groups:
  math: [math_backup]      # failover aliases for the "math" server

Testing

pytest tests/ -v

The test suite uses in-memory fake MCP servers (no real subprocesses required) and covers config parsing, circuit-breaker logic, prefix routing, tool aggregation, failover, and end-to-end gateway behaviour.

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-0ne

    ahostbr
    A
    license
    Not graded
    quality
    C
    maintenance
    A standalone MCP gateway that multiplexes multiple backend MCP servers behind a single endpoint, supporting both HTTP and stdio transports. It allows users to dynamically manage backends at runtime and organizes tools using a configurable namespace prefix.
    MIT

  • mcpstead

    ahkohd
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP Gateway that aggregates multiple upstream MCP servers into a single endpoint with persistent connections, tool registry, and authentication.
    14 npm
    2
    MIT

  • OmniMCP Router

    Simonc44
    A
    license
    Not graded
    quality
    A
    maintenance
    A universal MCP gateway that aggregates multiple MCP servers into a single endpoint, providing features like hot-reload, auto-healing, and a hook system for request/response mutation.
    1
    MIT