# 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.

Every link below is Markdown. Start with the architecture page, then read only what the task needs. A running broker serves the same integration guide over MCP on its `_broker` slot (`broker_guide`, `broker_diagnose`), completed with its effective configuration; when it disagrees with these pages, it wins. Packages: `@cyanmycelium/mcp-broker` (the broker, CLI and library) and `@cyanmycelium/mcp-broker-provider` (publish an MCP server into a slot) on npm. Source: https://github.com/pandaGaume/mcp-broker.

## Start here

- [agents/architecture.md](https://pandagaume.github.io/mcp-broker/agents/architecture.md): the map: every layer, its key rule, its specification and its source
- [AGENTS.md](https://pandagaume.github.io/mcp-broker/AGENTS.md): for a coding agent embedding the broker: topology table, transport/path pairing rule, copy-pasteable configurations, reserved slots, symptom-to-fix table
- [positioning.md](https://pandagaume.github.io/mcp-broker/positioning.md): what mcp-broker is, in one sentence and three proofs

## Integration guide

- [guide/index.md](https://pandagaume.github.io/mcp-broker/guide/index.md): What the broker is, the transport pairing rule, and which page to read next.
- [guide/publish-provider.md](https://pandagaume.github.io/mcp-broker/guide/publish-provider.md): Put an MCP server into a slot: the transport/path pairing rule, the aggregate opt-in, the lifecycle, browser limits.
- [guide/connect-client.md](https://pandagaume.github.io/mcp-broker/guide/connect-client.md): Reach a slot: the four client transports, the reserved `_broker` and `_all` slots, origins, authorization, error codes.
- [guide/host-config.md](https://pandagaume.github.io/mcp-broker/guide/host-config.md): Wire Claude Desktop or another stdio host: why the bridge must target `_all`, the recipe, the one-broker-per-port rule.
- [guide/deploy.md](https://pandagaume.github.io/mcp-broker/guide/deploy.md): Embed as a library or run as a process: startup ordering, topologies, configuration, static files, TLS, shutdown.
- [guide/troubleshooting.md](https://pandagaume.github.io/mcp-broker/guide/troubleshooting.md): Symptom to cause to fix, starting with the silent failures that produce no log line anywhere.

## Specifications

- [architecture.md](https://pandagaume.github.io/mcp-broker/architecture.md): roles, provider and client transports, per-slot state, the reserved `_broker` and `_all` slots
- [protocol.md](https://pandagaume.github.io/mcp-broker/protocol.md): wire protocol: provider framings, envelopes, the aggregate opt-in, resource subscriptions, error envelopes
- [endpoints.md](https://pandagaume.github.io/mcp-broker/endpoints.md): every HTTP and WebSocket endpoint and what it requires
- [authorization.md](https://pandagaume.github.io/mcp-broker/authorization.md): OAuth 2.1 resource server, provider authentication, scopes, `_all` filtering
- [hierarchical-authorization.md](https://pandagaume.github.io/mcp-broker/hierarchical-authorization.md): roles, ISA-95 aligned resource paths, inherited permissions, explicit deny, provider namespaces
- [telemetry.md](https://pandagaume.github.io/mcp-broker/telemetry.md): trace propagation, the `broker/telemetry` notification, OTLP export, PDU data security
- [node/packages/broker/docs/config.md](https://pandagaume.github.io/mcp-broker/node/packages/broker/docs/config.md): every configuration key, default and environment variable
- [node/packages/broker/docs/execution-limits.md](https://pandagaume.github.io/mcp-broker/node/packages/broker/docs/execution-limits.md): concurrency, rate and budget limits
- [node/packages/broker/docs/plugins.md](https://pandagaume.github.io/mcp-broker/node/packages/broker/docs/plugins.md): deployment plugins, API version 1
- [node/packages/broker/docs/testing.md](https://pandagaume.github.io/mcp-broker/node/packages/broker/docs/testing.md): `startTestBroker()`: a real broker for tests, with callers and provider identities
- [packages.md](https://pandagaume.github.io/mcp-broker/packages.md): the npm packages and what belongs in each
- [node/packages/broker/README.md](https://pandagaume.github.io/mcp-broker/node/packages/broker/README.md): the broker package: CLI, environment variables, programmatic API
- [node/packages/provider/README.md](https://pandagaume.github.io/mcp-broker/node/packages/provider/README.md): the provider package: DirectTransport, MultiplexTransport

## Device side

- [c/README.md](https://pandagaume.github.io/mcp-broker/c/README.md): the C99 side: why it stops at the transport
- [c/libmcpb/README.md](https://pandagaume.github.io/mcp-broker/c/libmcpb/README.md): libmcpb, the allocation-free tunnel client
- [c/espressif/README.md](https://pandagaume.github.io/mcp-broker/c/espressif/README.md): ESP-IDF component `mcpb_esp` for the ESP32
- [c/unreal/README.md](https://pandagaume.github.io/mcp-broker/c/unreal/README.md): Unreal Engine 5 plugin `McpBroker`, many slots on one socket
- [python/README.md](https://pandagaume.github.io/mcp-broker/python/README.md): Python tools, resources and prompts over libmcpb

## Samples

- [samples/index.json](https://pandagaume.github.io/mcp-broker/samples/index.json): machine-readable index: when to use each sample, the exact command, what success looks like
- [samples/README.md](https://pandagaume.github.io/mcp-broker/samples/README.md): the runnable Node integrations

## Optional

- [CHANGELOG.md](https://pandagaume.github.io/mcp-broker/CHANGELOG.md): every release
- [HOWTO.md](https://pandagaume.github.io/mcp-broker/HOWTO.md): in French: from open development to production, policy tests with `auth.dev`, mDNS discovery
- [mhs-positioning.md](https://pandagaume.github.io/mcp-broker/mhs-positioning.md): mcp-broker and the Model Hardware Standard
- [design/declarations-by-slot.md](https://pandagaume.github.io/mcp-broker/design/declarations-by-slot.md): design note, in French, not the reference
- [design/limits-by-pattern.md](https://pandagaume.github.io/mcp-broker/design/limits-by-pattern.md): design note, in French, not the reference