MCP Mesh

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