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

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