Skip to main content
Glama
Symbia-Labs

MCP Mesh

by Symbia-Labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

MCP Mesh

DEPRECATED: This package has been absorbed into mcp-iot-gateway. The federation functionality is now built-in to the gateway as the @mcp-iot-gateway/core federation module. This repository is archived for reference only.

Peer-to-peer federation for MCP servers.

MCP Mesh enables decentralized, peer-to-peer communication between MCP servers. It solves the fundamental limitation of MCP's client-server model: a single client can only connect to one server at a time.

                    ┌─────────────┐
                    │   Claude    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  mcp-mesh   │  ← One connection
                    └──────┬──────┘
                           │ bridges to many
              ┌────────────┴────────────┐
              │                         │
       ┌──────▼──────┐          ┌──────▼──────┐
       │   factory   │◀────────▶│    edge     │
       │   gateway   │  peers   │   gateway   │
       └─────────────┘          └─────────────┘

Features

  • Bridge Mode - Re-export remote tools locally with prefixes (factory_iot_discover)

  • P2P Connections - Direct node-to-node communication

  • Hub Mode - Optional central coordinator for network management

  • meshctl CLI - Hamachi-style network management

  • Pure MCP - No protocol extensions, works with any MCP client

Related MCP server: GameDev-MCP-Server

Installation

npm install mcp-mesh

Or run directly:

npx mcp-mesh --help

Quick Start

P2P Mode (Direct Connections)

Start a mesh node that bridges to other gateways:

# Start mesh node bridging to factory and edge gateways
mcp-mesh --port 45679 --name "my-mesh" --bridge factory --bridge edge

The bridged tools become available with prefixes:

  • factory_iot_discover → calls iot_discover on factory

  • edge_gateway_status → calls gateway_status on edge

Hub Mode (Centralized Network)

Start a hub for network coordination:

# Start hub
mcp-mesh --hub --port 45679 --name "central" --network "mycompany"

# Join from other nodes
mcp-mesh --port 45680 --name "factory-gw" --join http://hub:45679/mcp

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-mesh": {
      "command": "npx",
      "args": [
        "mcp-mesh",
        "--stdio",
        "--name", "claude-desktop",
        "--bridge", "factory",
        "--bridge", "edge"
      ]
    }
  }
}

CLI Reference

mcp-mesh

mcp-mesh [options]

Options:
  --stdio           Use stdio transport (for MCP clients)
  --port <port>     HTTP server port (default: 45679)
  --name <name>     Human-readable name for this node
  --bridge <spec>   Bridge to a peer (UUID, name, or URL). Repeatable.
  --peer <key=url>  Connect to a peer without bridging. Repeatable.
  --hub             Run as hub (central coordinator)
  --join <url>      Join a hub network by URL
  --network <id>    Network ID (for hub mode)

meshctl

Network management CLI (Hamachi-style):

meshctl status              Show local node status
meshctl list                List all nodes in directory
meshctl networks            List available hubs
meshctl network <hub-url>   Show network details
meshctl join <hub-url>      Join a network
meshctl connect <peer>      Connect to peer
meshctl disconnect <peer>   Disconnect from peer

API Usage

Basic Node

import { MeshNode, registerMeshTools } from "mcp-mesh";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

// Create mesh node
const node = new MeshNode({
  name: "my-server",
  url: "http://localhost:45678/mcp",
});

// Add mesh tools to your MCP server
const server = new McpServer({ name: "my-server", version: "1.0" });
registerMeshTools(server, node);

// Connect to peers
await node.bridge("factory");  // Bridge with prefix
await node.connectPeer({ key: "edge", url: "http://edge:45678/mcp" });

Hub Mode

const hub = new MeshNode({
  name: "central-hub",
  hub: true,
  networkId: "mycompany",
});

// Nodes register automatically via mesh_hub_register tool
// Or programmatically:
hub.hubRegister({
  id: "node-uuid",
  name: "factory",
  url: "http://factory:45678/mcp",
});

// Get network status
const stats = hub.hubStats();
const nodes = hub.hubListNodes({ onlineOnly: true });

Directory Lookup

import { MeshDirectory } from "mcp-mesh";

const directory = new MeshDirectory();

// List all known nodes
const nodes = directory.list();

// Look up by name or UUID
const factory = directory.lookup("factory");
console.log(factory?.url);  // http://127.0.0.1:45678/mcp

// Resolve any specifier (URL, UUID, or name)
const entry = directory.resolve("factory");

MCP Tools

When registerMeshTools() is called, these tools are added:

Peer Management

Tool

Description

mesh_list_peers

List all peer connections

mesh_add_peer

Connect to a peer

mesh_remove_peer

Disconnect from a peer

mesh_call_peer

Call a tool on a peer

mesh_list_peer_tools

List tools on a peer

Bridge Mode

Tool

Description

mesh_list_bridged_tools

List tools from bridge peers

mesh_call_bridged

Call a bridged tool

Directory

Tool

Description

mesh_directory_list

List all nodes in directory

mesh_directory_lookup

Look up a node

mesh_node_info

Get this node's info

Hub Mode (when --hub)

Tool

Description

mesh_hub_register

Register a node with hub

mesh_hub_heartbeat

Send heartbeat

mesh_hub_list_nodes

List registered nodes

mesh_hub_stats

Get hub statistics

mesh_hub_connect_node

Connect to a registered node

Configuration

Environment Variables

Variable

Description

Default

MCP_MESH_DATA_DIR

Data directory

~/.config/mcp-mesh

MCP_MESH_PEERS

Peers file path

~/.config/mcp-mesh/peers

Peers File

The directory file at ~/.config/mcp-mesh/peers uses a hosts-style format:

# MCP Mesh Peers
# Format: UUID  URL  [NAME]
#
a7196323-dcc1-4109-abf5-b47c2f99f920  http://127.0.0.1:45678/mcp  factory
9f157a51-7aaa-4f2c-bc38-3c791b604892  http://127.0.0.1:45679/mcp  edge

Architecture

See ARCHITECTURE.md for detailed design documentation.

Topology Options

P2P (Decentralized)

    A ←──→ B
    ↑       ↑
    │       │
    ↓       ↓
    C ←──→ D

  • No single point of failure

  • Works offline/air-gapped

  • Each node manages its own connections

Hub (Centralized)

        Hub
       / | \
      A  B  C

  • Central registry and coordination

  • Easier network management

  • Better for enterprise/audit requirements

Hybrid

        Hub
       / | \
    Site Site Site
     /\   |    /\
    A  B  C   D  E

  • Hub for cross-site coordination

  • P2P within sites

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

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers