Skip to main content
Glama

npm CI CI (C) License

mcp-broker

Puts many MCP servers behind one host and one port: browsers, ESP32 boards, Unreal Engine simulations and stdio tools publish into named slots, and any standard MCP client reaches each one, or all of them aggregated, over Streamable HTTP, SSE, WebSocket or stdio. MCP is the Model Context Protocol. The broker registers itself as an MCP server under the reserved slot _broker, so any client can discover what is routable through standard MCP tools, and read the integration guide the broker serves about itself.

Working with an AI coding agent? Point it at AGENTS.md first. It is the single self-contained file: topology table, the transport/path pairing rule, copy-pasteable configurations, the reserved slots, and a symptom-to-fix table. A running broker documents itself over MCP through broker_guide and broker_diagnose on the _broker slot, which is better still.

Why a broker

Real-world MCP deployments rarely consist of a single isolated server. An organization typically wants to expose, behind one endpoint:

  • industrial assets (PLCs, SCADA, machine telemetry) wrapped as MCP servers

  • sensor and data sources that an agent can query on demand

  • agent hosts (micro-containers, headless engines, RPA bots) reachable as tools

mcp-broker is the relay layer that lets all of those connect to a central point and be reached by MCP clients without each client having to know every backend.

Related MCP server: MCPDog

From simulation to the world

The providers do not have to be Node processes. The same tunnel client exists in C99 (c/libmcpb), with no allocation and no platform header, and it runs in two places that matter to each other:

  • on the device, an ESP32 under ESP-IDF (c/espressif): one FreeRTOS task, 7.4 KB of flash, one socket for the device's MCP server;

  • in the simulator, an Unreal Engine 5 plugin (c/unreal): one socket for every simulated device the engine hosts, multiplexed, because an engine is one process.

Both publish to the same broker, under the same slot names, with the same tool schemas. An agent that learned to drive the simulated machine drives the real one with the same calls; nothing on its side changes except which provider answers. That is the whole point of putting a broker between the agent and the equipment: the agent's world is the broker, and the broker does not care whether a slot is a game object or a board on a bench.

          Unreal Engine 5 (simulation)                    ESP32 boards (the world)
          ┌────────────────────────────┐                  ┌──────────┐  ┌──────────┐
          │ McpBroker plugin           │                  │ mcpb_esp │  │ mcpb_esp │
          │ slots: pump-1, pump-2, ... │                  │ pump-1   │  │ pump-2   │
          └─────────────┬──────────────┘                  └────┬─────┘  └────┬─────┘
                        │ one socket, /providers               │ /provider/pump-1 ...
                        └──────────────────┬───────────────────┴──────────────┘
                                           ▼
                                      mcp-broker  ──  _all  ──▶  the agent

The C side is transport only: libmcpb carries JSON-RPC bytes and never interprets them, so the MCP layer stays whatever the host already has (a C++ server on the board and in the engine, mcp-core in Node or a browser). See c/README.md for why that boundary is where it is.

Python tools use that same C99 transport through a native shared library and ctypes: python/ exposes tools, resources and prompts through Provider, with TLS, Multiplex groups, subscriptions, JSON conversion, bounded execution and native polling during long handler calls.

Repository layout

This repo is a multi-implementation reference. Each language lives under its own folder, with its own build, dependencies, and release pipeline.

mcp-broker/
├── node/                       ← TypeScript implementation (current)
│   └── packages/               ← npm workspace
│       ├── broker/             ← the broker itself
│       └── provider/           ← tunnel wire contract + publishing a server to a slot
├── c/                          ← the device side, in C99
│   ├── libmcpb/                ← the tunnel client: WebSocket, dedicated and multiplexed endpoints, reconnection, events
│   ├── ports/                  ← the six-function port per platform: host (Linux/macOS/Windows), espressif, unreal
│   ├── espressif/              ← ESP-IDF component and a Wi-Fi sample for the ESP32
│   ├── unreal/                 ← Unreal Engine 5 plugin and a host project
│   ├── samples/                ← the transport-only echo provider the samples share
│   └── tests/                  ← roundtrip against the Node broker, overnight soak
├── python/                     ← Python tools over the libmcpb native transport
├── dotnet/                     ← .NET implementation (planned)
├── samples/                    ← five runnable Node integrations
├── docs/                       ← protocol, architecture, endpoints, and the website
├── AGENTS.md                   ← start here if you are an AI coding agent
├── CHANGELOG.md
├── .github/workflows/          ← CI + release pipelines per package
└── mcp-broker.code-workspace

The two ends of the tunnel share one repository on purpose: a change to the envelope protocol touches the client transport and the broker at once, so it lands in a single commit and neither end can drift ahead of the other.

Open mcp-broker.code-workspace in VSCode for a multi-root workspace with the right tooling per folder.

Implementation status

Implementation

Status

Package

Tag prefix

node/packages/broker/

published

@cyanmycelium/mcp-broker on npm

node-v*

node/packages/provider/

published

@cyanmycelium/mcp-broker-provider on npm

provider-v*

c/libmcpb/

0.4.2, consumed from the repository

none: C99 sources, compiled into the firmware or the engine module

c-v*

c/espressif/

validated on an Arduino Nano ESP32, built for the S3 in CI

ESP-IDF component mcpb_esp

with c-v*

c/unreal/

built and run on UE 5.7

plugin McpBroker

with c-v*

dotnet/

planned

CyanMycelium.Mcp.Broker on NuGet

dotnet-v*

Each package carries its own .npmrc with the matching tag-version-prefix, so run npm version from inside the package directory rather than from the workspace root: npm ignores per-workspace .npmrc files when invoked at the root, and you would get an unprefixed v* tag that no release workflow listens to.

Quick start (Node)

npx @cyanmycelium/mcp-broker

The broker starts on http://localhost:3000. Connect your MCP provider to ws://localhost:3000/provider/<name>, then point any MCP client at http://localhost:3000/<name>/mcp.

A provider's transport and its URL path are a matched pair: DirectTransport pairs with ws://<host>/provider/<name> (plain JSON-RPC frames), MultiplexTransport pairs with ws://<host>/providers (envelopes). ws://<host>/providers/<name> is neither, and is silently accepted as a client connection. See AGENTS.md.

Full instructions, environment variables, and programmatic API in node/packages/broker/README.md.

Quick start (a device, or a simulator)

An ESP32 with ESP-IDF, on the same broker:

idf.py -C c/espressif/samples/provider set-target esp32s3
idf.py -C c/espressif/samples/provider menuconfig      # Provider sample: Wi-Fi, broker host and port, slot name
idf.py -C c/espressif/samples/provider flash monitor

Unreal Engine 5, publishing two slots on one socket:

& "$UE\Engine\Build\BatchFiles\Build.bat" McpBrokerSampleEditor Win64 Development -Project="c\unreal\Sample\McpBrokerSample.uproject"
& "$UE\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "c\unreal\Sample\McpBrokerSample.uproject" -game -nullrhi -McpBrokerHost=127.0.0.1

In both cases the broker is this repository's, started from a checkout with npm start in node/packages/broker after npm run build in node/ (it listens on 0.0.0.0:3000, so the board reaches it at the PC's address), and tools/call echo on http://<broker>:3000/<slot>/mcp answers from the device or the engine, and _all lists the slot next to every other provider. c/README.md is the map of that folder.

Documentation

  • HOWTO.md (in French): local development with openGuard(), policy tests with auth.dev, production with OAuth, and opt-in LAN discovery through mDNS.

The website, pandagaume.github.io/mcp-broker, publishes every document below as Markdown, indexed for agents in llms.txt. docs/agents/architecture.md is the map: every layer of the broker, its key rule, its specification and its source.

Start with AGENTS.md if you want one file that covers the decisions, or samples/ if you would rather run something first: five self-contained integrations that start what they need and prove themselves end to end, indexed for agents in samples/index.json. Then, by depth:

License

Apache-2.0. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Aggregates multiple upstream MCP servers (stdio, streamable-http, sse, websocket) behind a single streamable-HTTP endpoint with declarative configuration, namespacing, filtering, and auto-reload.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Aggregates multiple MCP sub-servers into a single unified entry point, supporting stdio and Streamable HTTP protocols, with a web-based management interface for configuration, routing, and tool management.
      17 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables connecting and managing multiple backend MCP resource servers of Stdio, SSE, and Streamable HTTP types, then exposing their aggregated tools and resources through unified SSE/HTTP endpoints or as a single Stdio server. It routes requests to the appropriate backend and supports optional web admin management, authentication, and concurrent client connections.
      120 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables clients to connect to, manage, and aggregate multiple backend MCP servers and access their combined tools and resources through unified SSE or Streamable HTTP endpoints, or as a single Stdio server. It provides request routing, optional authentication, granular tool controls, and an optional web admin interface.
      120 npm
      MIT