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, null for 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 buffer to find an editor operation without knowing its broker. Call a returned PREFIX.TOOL via call-tool.

list-tools

Queries downstream servers for their tool definitions and refreshes the combined list. An optional broker argument selects one exact downstream prefix, including hidden servers and excluding the multibroker's own tools. Without broker, hidden servers are omitted. Unknown broker names or arguments are errors. Unreachable servers are omitted from tool listings but reported by discover-brokers.

call-tool

Calls a downstream tool by its PREFIX.TOOL name 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 --stdio or --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, or none. none replies with a standard decline without invoking any UI. Spawned stdio children delegate to the broker with their own default mcp. 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.

--hidden

Omit the preceding child's tools from ordinary tool discovery, including unfiltered list-tools. Discover its definitions with list-tools specifying its broker prefix. 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 --eager and --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 --bearer after its URL instead.

--tool-help

Lists only the broker's own tools. Use its list-tools tool to discover individual downstream registries.

--auto-allow TOOL[,ACTION[,CAPABILITY]]

Matches the broker-visible tool names, not a downstream server's independent permission checks.