mcp-broker
Provides an ESP-IDF component and sample for ESP32 devices to publish their MCP server into named broker slots over a single socket, with support validated on an Arduino Nano ESP32 and builds for ESP32-S3.
Provides an Unreal Engine 5 plugin that publishes simulated devices as named broker slots over one multiplexed socket, allowing agents to drive simulated machines with the same MCP calls used for real hardware.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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_guideandbroker_diagnoseon the_brokerslot, 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 agentThe 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-workspaceThe 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 |
published |
|
| |
published |
|
| |
0.4.2, consumed from the repository | none: C99 sources, compiled into the firmware or the engine module |
| |
validated on an Arduino Nano ESP32, built for the S3 in CI | ESP-IDF component | with | |
built and run on UE 5.7 | plugin | with | |
planned |
|
|
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-brokerThe 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 monitorUnreal 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.1In 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 withauth.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:
docs/packages.md: the packages, what belongs in each, and why
clientwas split intoproviderandconsumerdocs/architecture.md, overview, roles, request flow, the reserved
_brokerand_allslotsdocs/protocol.md, provider WebSocket framing, JSON-RPC envelopes, the aggregate opt-in frame
docs/telemetry.md, provider trace transport, MCU codec, bounded queue, OTLP export and PDU security
docs/endpoints.md: every HTTP and WS endpoint exposed by the broker
docs/authorization.md: OAuth 2.1 resource server, provider auth,
_allscope filtering (opt-in)docs/hierarchical-authorization.md: roles, ISA-95-aligned resource paths, inherited permissions, explicit deny, and provider namespaces
c/README.md, c/libmcpb/README.md, c/espressif/README.md, c/unreal/README.md: the device side, the tunnel client in C, the ESP32 component, the Unreal plugin
node/packages/broker/docs/config.md: every config key, default, and env var
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
MCP federation gateway: route, govern and observe agent tools across clouds and MCP servers.
Trust, freshness, policy, and discovery layer for public MCP servers.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAggregates multiple upstream MCP servers (stdio, streamable-http, sse, websocket) behind a single streamable-HTTP endpoint with declarative configuration, namespacing, filtering, and auto-reload.MIT
- AlicenseNot gradedqualityBmaintenanceAggregates 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 npm1MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT