NAME
mcp-multibroker - combine MCP servers under tool name prefixes
SYNOPSIS
mcp-multibroker files 'stdio:mcp-fs /home/alice/src/project' \
search https://example.org/mcp/ --bearer TOKEN
mcp-multibroker vim --- mcp-vim --bind :: --- --required
DESCRIPTION
mcp-multibroker combines several MCP servers behind one connection to your MCP client. You can give an assistant access to filesystem tools, Vim editors and other services by configuring them here, then connecting the client to this broker.
For each server, give a name prefix and an HTTP URL, a stdio:COMMAND, or --- PROGRAM ARG... --- to start it as a subprocess. These are the downstream servers. The multibroker starts or connects to them, obtains their tool definitions and forwards tool calls and replies between them and your client.
The prefix identifies which server a tool belongs to. For example, a filesystem server configured as files has a tool named files.read-lines. Your client can ask the multibroker which servers and tools are available, then call a tool by its prefixed name.
The connection from your MCP client to the multibroker is the upstream connection. It can use HTTP or stdin/stdout, independently of how the downstream servers connect. See AnyEvent::MCP::Intro for a complete setup example.
FIRST USE
Configure a local MCP client to start a multibroker with two servers:
mcp-multibroker --stdio \
files --- mcp-fs --name project /home/alice/src/project --- \
questions --- mcp-ask-user ---
The client launches only the broker; it starts children as needed. Ask:
Call discover-brokers and list-tools, then use files.workdirs
to show which project directories are configured.
files and questions are routing prefixes, not child instance names or permission profiles. Each child still applies its own permissions. The broker selects stdio automatically for bundled AnyEvent::MCP children. Third-party servers must support MCP over stdio in their own startup mode. You can replace a child with any stdio-speaking MCP server by putting its executable and arguments between the --- delimiters, or connect an existing HTTP server by URL; see "DOWNSTREAM SERVERS".
For HTTP clients, omit --stdio, leave the broker running, and obtain its upstream URL with --print-url using the same listener settings. For missing tools, try search-tools with keywords, or discover-brokers for connection errors and list-tools to refresh discovery; your MCP client may also need to refresh its cached list. --tool-help only shows the broker's own tools, not those of its children. Ordinary children start lazily. Use --eager after the child specification for services that accept independent connections, such as Vim or browser brokers.
TOOLS
The broker exposes four tools of its own:
- discover-brokers
-
Lists the configured downstream servers and their instructions by prefix. An entry is a string of instructions,
nullfor a reachable server with no instructions, or{error: MESSAGE}for an unreachable server. Hidden servers are listed, with instructions on how to discover their tools. - search-tools
-
Search complete tool definitions from all reachable downstream servers, including hidden ones, but not the broker's own tools. Uses BM25 keyword relevance, searching names, descriptions and argument names and descriptions. Returns up to 25 full tool definitions, ranked by relevance. For example, search for
edit lines in vim bufferto find an editor operation without knowing its broker. Call a returnedPREFIX.TOOLviacall-tool. - list-tools
-
Queries downstream servers for their tool definitions and refreshes the combined list. An optional
brokerargument selects one exact downstream prefix, including hidden servers and excluding the multibroker's own tools. Withoutbroker, hidden servers are omitted. Unknown broker names or arguments are errors. Unreachable servers are omitted from tool listings but reported bydiscover-brokers. - call-tool
-
Calls a downstream tool by its
PREFIX.TOOLname with the supplied arguments, including hidden servers. Calls to an unavailable server fail as tool errors; calls are not replayed after transport failures.
A refreshed list is a snapshot of what is reachable at that point. It includes configured servers and currently registered reverse connections. A listed server might become unavailable before a later call.
DOWNSTREAM SERVERS
Each prefix identifies one downstream server. HTTP URLs may include a URL-path token, or be followed by --bearer TOKEN. bearer and timeout defaults are read from [client PREFIX] in the global configuration; the URL in the command line overrides any configured url. Stdio children receive PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL=stdio and PERL_ANYEVENT_MCP_MULTIBROKER_ALIAS=PREFIX in their environment. The alias may be displayed in downstream permission prompts, without changing the server's instance name or permission rules.
For direct execution, use PREFIX --- PROGRAM ARG... ---:
mcp-multibroker vim --- mcp-vim --bind :: --- --eager \
files --- mcp-fs '/home/alice/project with spaces' ---
The next exact --- argument closes the list. Everything inside, including --, --eager and --bearer, is passed unchanged to the child. There is no shell interpretation. Empty arguments are preserved; the program must be nonempty. An empty list or missing closing delimiter is an error.
A subprocess can also connect to an MCP server on another machine via SSH:
mcp-multibroker remote-fs --- ssh remotehost mcp-fs --stdio --ask mcp /workdir ---
--stdio tells the remote mcp-fs to use stdin/stdout for MCP. It must be specified explicitly because the multibroker's environment variables are not passed through SSH. --ask mcp forwards permission prompts over MCP to the local multibroker, instead of trying to display dialogs on the remote host. The local broker then presents them according to its own --ask mode (normally using a local helper); see "PERMISSION PROMPTS".
stdio:COMMAND retains shell interpretation. Use it for shell syntax or when a child needs a literal --- argument. Quoting '---' in the delimited form cannot escape the delimiter: shell quoting is already gone.
Broker-wide options precede the first server entry. Downstream options follow that server's URL or closing ---; Getopt::Long stops at the next prefix. Options inside an argv list belong exclusively to the child.
--hidden after a server keeps its tools out of normal MCP tools/list and unfiltered list-tools results. This reduces the initial tool list for large or rarely used servers. discover-brokers still lists it; list-tools broker=PREFIX returns its definitions; search-tools includes hidden tools, and call-tool still works. Hiding affects advertisement, not permissions. --disable after a server excludes it entirely: no child is started, no HTTP connection is made, and its tools cannot be discovered or called. The prefix stays reserved so a reverse connection cannot take its place. This takes precedence over --eager and --required; remove the flag to re-enable the server.
--eager after either stdio form starts that child at multibroker startup rather than waiting for its first MCP use. This is useful for children that also provide their own TCP service, such as mcp-vim. Other stdio children remain lazy. Eager startup attempts one connection and logs failures; it does not continually restart failed children. --required implies --eager and makes the multibroker exit with failure if that child cannot initialize or later disconnects unexpectedly. A supervisor can then restart the broker. An explicitly accepted managed idle shutdown is not a failure; the child can be started again on the next use. Both options apply only to spawned stdio children, never remote HTTP peers.
Reverse connections
The HTTP listener also accepts authenticated reverse MCP connections. It can run with no configured downstream servers. With upstream stdio, add --listen to keep this listener active:
mcp-multibroker --stdio --listen --bind 127.0.0.1:31740
mcp-multibroker --bind 127.0.0.1:31740 --print-url
mcp-fs --connect http://127.0.0.1:31740/TOKEN/files /home/alice/project
Use the token returned by --print-url. The connecting server extracts the host, port, token and alias from this URL, sends ["mcp-connect", token, alias] followed by a newline, then ordinary MCP JSONL. The connection uses the HTTP listener but is not an HTTP request. With --tls-cert or --tls-key, the same port also accepts TLS, and --print-url prints HTTPS first and HTTP second. Reverse connections using https:// verify the listener certificate and hostname; http:// uses plaintext. It uses the same accepted tokens as HTTP. Authentication grants registration under any free alias; configured or connected aliases cannot be replaced.
The connecting program remains the MCP server. The multibroker attaches an MCP client and discovers its tools immediately. Forms and cancellation follow the same routes as other downstream connections. An unexpected disconnect fails pending calls, removes the registration and starts a new connection period. Refused TCP connections are retried every second, up to sixty times. Other TCP setup failures and TLS verification failures log an error and stop; there is no automatic downgrade to plaintext. No interrupted operation is replayed. Plain HTTP endpoint URLs do not provide transport encryption; use a trusted connection or tunnel as needed.
Process lifetime
Each downstream connection advertises anyevent-mcp/multibroker version 1 in its client capabilities. A spawned stdio child can request managed idle shutdown with anyevent-mcp/idle-exit. When no calls are outstanding, the broker may send anyevent-mcp/shutdown; the child acknowledges before exiting. This is optional and never makes HTTP children exit. Unexpected disconnects are logged, not proactively restarted. A later use reconnects.
PERMISSION PROMPTS
--ask helper (the default) answers downstream form challenges locally. Ordinary forms use anyevent-mcp-form-elicitation; permission requests keep their specialised permission dialogs. --ask mcp forwards modern challenges to the upstream client. --ask auto uses upstream form support when advertised, otherwise the local helper. Both modes deliberately trust the upstream client's user assertion when permission authority has been delegated to it. The multibroker forwards the original authenticated user with every tool call, even when a downstream saved permission rule resolves that request without another prompt. A decline or cancel is never retried through another interface. If a client advertises forms but silently declines them, select helper explicitly.
--ask tty and --ask yad select only the built-in terminal or YAD interface for both ordinary forms and permission dialogs. These modes ignore custom helper variables and do not fall back to another interface.
The broker advertises its local form support to downstream calls when it will handle their forms itself. In mcp mode it forwards the upstream caller's capabilities instead. Local forms work for HTTP and stdio children, including when the upstream caller cannot handle native input challenges. Continuation tokens remain opaque; the broker sends the human response back to the same downstream operation and returns its eventual result.
Spawned stdio children default to --ask mcp, delegating permissions to the multibroker, which handles them according to its own --ask mode. An explicit child --ask overrides this default. Independently running servers keep their own configuration. Spawned mcp-ask-user instances normally delegate presentation to this broker. Use --ask mcp on a separately started mcp-ask-user to delegate to its connecting client, including a multibroker.
Local permission and question dialogs share one queue. Set PERL_ANYEVENT_MCP_ELICITATION_HELPER to replace the form helper and PERL_ANYEVENT_MCP_PERMISSION_HELPER to replace the permission helper. Cancelling a tool call cancels its downstream operation and pending local prompt. Downstream notifications/progress are forwarded to the corresponding upstream request by its progress token, including through HTTP children.
CLIENT CONNECTION
The upstream listener uses "mcp_start" in AnyEvent::MCP::Server::Simple: HTTP without stdout output by default, or stdio when run by another broker. The service instance name defaults to default. Repeated --token TOKEN options before the broker pairs configure credentials accepted by the upstream HTTP listener. They are separate from --bearer after a downstream broker URL, which authenticates the client connection. --name NAME selects [instance NAME] in the global configuration, including its credentials and optional bind address. --bind ADDRESS[:PORT] overrides that address. The default is IPv4 loopback with a stable name-derived port in 16384..32767. Port zero requests an ephemeral port. --print-url prints the credential-bearing URL without opening a listener or starting children; it requires a nonzero port. Upstream stdio startup skips HTTP listener configuration unless --listen is specified; named HTTP children still load their client defaults. Browser origins are unrestricted by default; HTTP requests still require an accepted token. See AnyEvent::MCP::Intro for examples.
OPTIONS
Shared upstream switches are documented in "COMMON COMMAND-LINE OPTIONS" in AnyEvent::MCP::Server::Simple. Put broker-wide options before the first PREFIX/URL pair. Downstream options must immediately follow the server they configure.
Broker options
- --listen
-
Keep the upstream HTTP/extension listener active alongside
--stdioor--connect. Without those, HTTP is already the default. Applies to the broker, not its downstream servers. - --ask MODE
-
Select how downstream permission prompts are presented:
helper(default),tty,yad,mcp,auto, ornone.nonereplies with a standard decline without invoking any UI. Spawned stdio children delegate to the broker with their own defaultmcp. See "PERMISSION PROMPTS".
Downstream options
- --bearer TOKEN
-
Authenticate the preceding HTTP(S) child with a bearer token, not the broker's upstream listener. Supply after the child URL; invalid for stdio children.
-
Omit the preceding child's tools from ordinary tool discovery, including unfiltered
list-tools. Discover its definitions withlist-toolsspecifying itsbrokerprefix. Its tools remain callable by name. Applies to HTTP and stdio children. - --disable
-
Ignore the preceding downstream entry without removing it from the command line. No startup, discovery or calls; the prefix remains reserved. Overrides
--eagerand--required. Applies to HTTP and stdio children. - --eager
-
Start the preceding stdio child at broker startup instead of on first use. Not available for HTTP children.
- --required
-
Require the preceding stdio child to initialize and remain connected. Implies
--eager; an unexpected disconnect causes the broker to exit. Managed idle shutdown is permitted. Not available for HTTP children.
Shared-option behavior
- --name NAME
-
Select the upstream broker's instance (default
default). Does not affect downstream prefixes or their instance names. - --token TOKEN
-
Authenticate clients of the upstream broker. To authenticate an HTTP(S) child, use
--bearerafter its URL instead. - --tool-help
-
Lists only the broker's own tools. Use its
list-toolstool to discover individual downstream registries. - --auto-allow TOOL[,ACTION[,CAPABILITY]]
-
Matches the broker-visible tool names, not a downstream server's independent permission checks.