AnyEvent-MCP
view release on metacpan or search on metacpan
lib/AnyEvent/MCP/Intro.pod view on Meta::CPAN
C<mcp-webbrowser> works with explicitly approved browser tabs. Install
its companion userscript and connect each tab you want to expose; see
L</CONNECTED BROWSER PAGES>.
C<mcp-ask-user> lets the assistant ask you questions through a local
YAD or terminal dialog, or through the client's native form UI; see
L</Ask the client's human a question>.
C<mcp-http> makes HTTP(S) requests with method- and URL-scoped permissions.
It does not follow redirects automatically; see L</Use an HTTP request tool>.
C<mcp-imap> reads, searches and manages mailboxes. Configure the account
interactively before starting the server; see L</Read and organize mail>
and L<mcp-imap> for OAuth2 and account management.
To offer several servers over one MCP connection, use C<mcp-multibroker>.
It combines these servers with each other or with third-party MCP servers,
whether started locally over stdio or reached over HTTP. Their tools
appear under separate name prefixes; see L</COMBINING SERVERS> and
L<mcp-multibroker> for the full command syntax.
=head1 YOUR FIRST FILESYSTEM SERVER
Start with one project and one connection. You do not need a multibroker,
a hand-written configuration file or saved permission rules yet.
=head2 Choose stdio or HTTP
Use B<stdio> when your MCP client runs on the same machine and can launch
a server process. Configure the client to start the following command:
mcp-fs --stdio --name code /home/alice/src/project
The client starts this process and uses its stdin/stdout for MCP.
You do not start a second copy in a terminal, and there is no listener
URL or HTTP token to configure. Diagnostics go to stderr.
Clients that take a command and an argument array need these values:
command: mcp-fs
arguments: --stdio, --name, code, /home/alice/src/project
These describe separate arguments, not one shell command string.
Use an absolute executable path if the client cannot find C<mcp-fs>.
See L</CLIENT EXAMPLES> for examples of particular clients.
Use B<HTTP> when the client connects to an already-running server, or when
it cannot launch a local process. Start this in a terminal on the server
machine and leave it running:
mcp-fs --name code --bind :31741 /home/alice/src/project
In another terminal, obtain the matching connection URL:
mcp-fs --name code --bind :31741 --print-url
The second command prints a credential-bearing URL and exits without
opening a listener. Configure that URL in the client. The default address
is IPv4 loopback, so this example is reachable from the same machine only.
A hosted client needs a suitable tunnel or reachable endpoint; its own
C<localhost> is not your computer.
Repeat the same name and listener overrides when printing the URL.
Both commands must use the same user and configuration directory.
Port zero chooses an ephemeral port, which C<--print-url> cannot predict;
use an explicit port for this walkthrough.
The HTTP server generates and saves its private master secret when needed.
You can initialize it explicitly with C<anyevent-mcp init>, but that
command is unnecessary when configuration already exists and will refuse
to replace it. Keep the printed URL private: possession of its token
authenticates a client.
=head2 Make a useful request
Once your client reports that the server is connected, ask the LLM:
Show me the configured workdirs. List the top-level files in the
project, then read its README if it has one. Do not modify files
or run commands.
C<workdirs> returns the configured paths, sandbox grants, trusted mounts
and runtime paths. Listing names requests C<inspect> permission; reading
contents requests C<read> permission. Expect a permission prompt when
there is no saved rule allowing the operation.
Choose C<Allow once> for the first operation. The worker then runs with
the requested sandbox grants. A denial is a tool failure that the LLM
should report, rather than an empty file or a disconnected server.
See L</Your first permission dialog> for a walkthrough.
For a slightly larger task, ask:
Find TODO comments in this project and explain the three that look
most useful to address next. Do not modify files or run commands.
This can use C<find>, C<grep> and C<read-lines>. You need not write MCP
requests yourself. If a client offers its own tool-approval prompt, that
is an additional client policy; it does not replace mcp-fs's permissions.
=head2 Give the server a purpose
To explain why an instance exists, provide a short purpose:
mcp-fs --stdio --name memory \
--custom-instructions 'Use this server to retrieve and store persistent memory.' \
/home/alice/memory
For persistent configuration, use C<custom_instructions> in the global
configuration's C<[program mcp-fs]> or C<[instance memory]> section. Instance
settings override program settings; the command line overrides both.
This purpose appears first in the advertised MCP instructions so a model can
decide whether to discover the server's tools.
Servers using C<AnyEvent::MCP::Server::Simple> also expose the instance
purpose and complete operating instructions as a C<meta-instructions> tool
description. Calling that tool returns the complete text when a client
truncates descriptions. Clients that understand MCP server instructions
still receive a short purpose or routing hint at discovery time, followed
by an automatic pointer to the full instructions in the tool description.
lib/AnyEvent/MCP/Intro.pod view on Meta::CPAN
anyevent-mcp edit-rules-file /path/to/rules.ini
A failed attempt to save a permanent rule is an error, not a successful
permanent approval. The file mode is preserved when saved through these
commands. For full syntax and programming interfaces, see
L<AnyEvent::MCP::Server::Permissions>.
=head2 Choose where to ask
The default C<helper> mode runs C<anyevent-mcp-askpermission> on the server
machine. It tries YAD, then C</dev/tty>, then denies if neither can be used.
The helper inherits the server's display environment.
C<--ask tty> and C<--ask yad> instead force the built-in terminal or YAD
interface. They ignore custom helper settings and never try another
interface. These modes work for permission prompts and ordinary forms,
including forms handled by a multibroker.
C<PERL_ANYEVENT_MCP_PERMISSION_HELPER> selects a different executable.
For a modern client supporting MCP form elicitation, you can instead use:
mcp-fs --stdio --name code --ask auto /home/alice/src/project
C<auto> uses the client's form support when advertised for that request,
otherwise the local helper. C<mcp> requires that support and fails when
unavailable. It does not silently fall back. Use client-side permission
approval only when that client is a trusted authority to grant access.
C<--ask none> automatically declines anything that would otherwise need
human input, without launching a helper or eliciting through MCP. Saved
and automatic allow/deny permission rules continue to apply. The multibroker
returns an ordinary decline to requesting downstream servers.
To set the default for servers using the shared permission engine:
PERL_ANYEVENT_MCP_PERMISSION_ASK=auto \
mcp-fs --stdio --name code /home/alice/src/project
An explicit application C<ask> setting or C<--ask> overrides the environment.
The multibroker sets this default to C<mcp> for spawned stdio children,
regardless of its own asking mode. Children delegate permission prompts to
their calling MCP client; the multibroker handles or forwards those prompts
according to its own C<--ask> mode. An explicit child C<--ask> still overrides
this default. Independently running HTTP servers keep their own configuration.
The multibroker can handle form elicitation locally for both stdio and HTTP
children. C<--ask helper> selects local dialogs even if the upstream client
advertises native forms; C<--ask mcp> forwards forms upstream, and C<auto>
uses native forms when advertised. If a client claims support but silently
declines questions, use C<helper>. A decline never causes a fallback prompt.
Standalone C<mcp-ask-user> also supports these modes and defaults to the
local helper. A question is different from an approval: answering it does
not grant a filesystem worker any authority.
=head1 COMBINING SERVERS
Once the first connection works, C<mcp-multibroker> lets you give the
client one connection for several MCP servers. It works with the servers
in this distribution and with third-party MCP servers, including ones
written in other languages. Each downstream server can be a local
subprocess communicating over stdio or an existing HTTP endpoint; you
can mix both in one broker. The broker discovers their tools and
forwards calls to the appropriate server without changing how that
server implements its tools.
For example, combine two filesystem instances:
mcp-multibroker --name tools --bind :31740 \
code 'stdio:mcp-fs --name code /home/alice/src/project' \
notes 'stdio:mcp-fs --name notes /home/alice/notes'
Quote each C<stdio:> shell command as one argument.
The broker supplies the child's stdio environment and starts ordinary
children lazily, on first use. The explicit child names give them separate
permission profiles C<fs-code> and C<fs-notes>.
Obtain the upstream HTTP URL with:
mcp-multibroker --name tools --bind :31740 --print-url
Configure this URL in place of the client's old direct connection.
The client can now see C<code.grep>, C<code.read-lines>, C<notes.find>
and other prefixed tools. It does not need a separate connection to each
child.
For a client launching the multibroker locally, configure:
mcp-multibroker --stdio --name tools \
code 'stdio:mcp-fs --name code /home/alice/src/project' \
notes 'stdio:mcp-fs --name notes /home/alice/notes'
C<--stdio> selects the upstream connection. The child commands still use
C<stdio:>; that selects each downstream connection independently.
No upstream HTTP URL is needed in this case.
The same setup can include Vim, browser pages, a third-party stdio
server or a remote HTTP service. See L</Add an HTTP child> for an
example mixing local and remote servers, and L<mcp-multibroker/DOWNSTREAM
SERVERS> for the complete syntax, including direct argv execution,
credentials and per-child options.
=head2 Discover and refresh tools
Ask the LLM:
Call discover-brokers and list-tools, then show me which servers
are available and what each is for.
C<discover-brokers> returns advertised instructions (which may be short),
no instructions, or an error for each configured server.
C<list-tools> requests current tool definitions, including any prefixed
C<meta-instructions> tools and their full instruction descriptions;
unreachable servers are omitted. A reachable server can still fail later.
If the client still has an old direct tool list, C<call-tool> can invoke
an exact prefixed name found by C<list-tools>. Refresh the client's MCP
connection if it continues to hide newly available tools.
Discovery queries configured servers and currently registered reverse
connections. Changing the static downstream command still requires a restart.
=head2 Let a server connect to the multibroker
To add independently started servers without editing the multibroker command,
keep its HTTP/extension listener active alongside stdio:
mcp-multibroker --stdio --listen --bind 127.0.0.1:31740
mcp-multibroker --bind 127.0.0.1:31740 --print-url
Append an alias to the returned credential-bearing URL:
mcp-fs --connect http://127.0.0.1:31740/TOKEN/files /home/alice/project
The filesystem server initiates the TCP connection but remains the MCP server.
The multibroker authenticates the same token used for HTTP, registers the
alias and discovers the tools. A configured or connected alias cannot be
replaced. An unexpected disconnect starts a new connection period; refused TCP
connections retry once per second, at most sixty times. Other TCP errors and
TLS verification failures log an error and stop. Pending calls fail and are
never replayed. Remote registration does not grant spawned-child shutdown
authority to the multibroker.
The hello is a raw JSON line, followed by ordinary MCP JSONL on the same
socket; the HTTP-shaped URL is an address and credential, not an HTTP request.
C<https://> reverse URLs enable verified TLS; C<http://> uses plaintext.
A certificate mismatch is an error, not a reason to fall back to HTTP.
With C<--tls-cert> and C<--tls-key> on the listener, C<--print-url> gives
HTTPS and HTTP URL prefixes. For HTTPS, use a trusted certificate whose
hostname matches the URL. An HTTP listener is already active by default
when upstream is HTTP.
=head2 Add an HTTP child
A broker can mix spawned stdio servers and existing HTTP endpoints,
including independently implemented third-party servers:
mcp-multibroker --stdio \
code 'stdio:mcp-fs --name code /home/alice/src/project' \
remote https://example.org/mcp/ --bearer TOKEN
C<--bearer> immediately after the HTTP pair belongs to that child.
C<--token> before all pairs configures the multibroker's own HTTP listener.
They authenticate different connections.
To avoid putting a child's bearer token in the startup command, add:
[client remote]
bearer = TOKEN
timeout = 300
to the private global configuration, and omit C<--bearer> from the command.
The prefix C<remote> selects these client defaults. The command-line URL
still chooses the endpoint. Use the actual credential accepted by that
server, not the literal placeholder C<TOKEN>.
A token already present in a child's URL needs no separate bearer option.
The bundled servers use static URL-safe tokens; they do not validate
OAuth access tokens or implement HTTP Basic authentication.
Use TLS or an appropriate tunnel when credentials cross untrusted networks.
The multibroker does not put every child inside the mcp-fs sandbox.
Each process or remote service has its own authority and enforcement.
=head2 Add a live Vim editor
Install the Vim plugin using L<mcp-vim/VIM PLUGIN INSTALLATION>. It is
included in the source distribution but is not installed by Perl's
C<make install>.
Without a multibroker, configure the MCP client to launch:
mcp-vim --stdio --name editor
Even in stdio mode, mcp-vim listens separately for editor connections.
If using a multibroker, start its child eagerly so Vim can connect
before the first MCP tool call:
mcp-multibroker --stdio \
code 'stdio:mcp-fs --name code /home/alice/src/project' \
vim 'stdio:mcp-vim --name editor' --eager
In another terminal, obtain the editor broker's URL prefix:
mcp-vim --name editor --print-url
Append the desired target name in Vim:
:Mcp http://HOST:PORT/TOKEN/my-editor
Use the actual printed prefix in place of C<http://HOST:PORT/TOKEN/>.
Ask the LLM to call C<targets>, then C<state> before reading or editing
buffers (C<vim.targets> and C<vim.state> through the multibroker).
These tools see live, possibly unsaved buffers. Edits require a current
changedtick and do not save files to disk.
To pass arguments directly, use C<PREFIX --- PROGRAM ARG... --->:
mcp-multibroker --stdio \
vim --- mcp-vim --name editor --bind :: --- --eager \
code --- mcp-fs --name code '/home/alice/project with spaces' ---
Only the invoking shell processes quoting. The broker passes all arguments
between the delimiters unchanged, including empty arguments and child options.
Use C<stdio:COMMAND> for shell syntax or a literal C<---> child argument.
An empty command or missing closing delimiter is an error.
C<--eager> belongs immediately after its stdio URL or closing C<--->.
An eager connection failure is logged; the broker does not continuously
restart the child. Later tool use can try connecting again.
=head2 Ask the client's human a question
To let the assistant ask you questions, configure its MCP client to launch:
lib/AnyEvent/MCP/Intro.pod view on Meta::CPAN
Changing flags, moving messages and expunging require separate permissions.
Marking C<\\Deleted> does not remove a message permanently; expunging does.
After an interrupted write, inspect the mailbox before attempting it again.
APPEND stores mail (including drafts) but does not send it. See
L<mcp-imap/TOOLS> for complete operations and limits.
=head2 Use an HTTP request tool
Launch C<mcp-http --stdio> or combine it as C<web --- mcp-http --stdio --->.
For example, ask your assistant:
Fetch https://example.org/ and show the status and page title.
Do not send a modifying request.
A C<request> call can use:
{"url": "https://example.org/", "method": "GET", "max_bytes": 8192}
Permissions distinguish HTTP methods and URL scopes; allowing a GET does
not authorize a POST. C<grep> and C<regex> can filter response text, while
C<cookie_jar> must be passed between calls by the caller. Redirects and
automatic retries are disabled. See L<mcp-http> for response limits and
network trust boundaries.
=head1 CONNECTED BROWSER PAGES
C<mcp-webbrowser> is the browser-page counterpart to C<mcp-vim>. It exposes
only tabs explicitly allowed by the browser user. Configure your MCP client
to launch:
mcp-webbrowser --stdio
The broker keeps its own HTTP/WebSocket listener active even in stdio mode;
the userscript connects to that listener, not to MCP's stdio stream.
In a separate terminal, obtain its URL:
mcp-webbrowser --print-url
Use the same instance name and configuration as the broker. Keep this
credential-bearing URL private.
Install the companion userscript from
C<webbrowser/mcp-webbrowser.user.js> in the source distribution or from
L<https://dist.schmorp.de/mcp-webbrowser/1/mcp-webbrowser.user.js>.
Chromium with ScriptCat has been tested. On a tab you want to expose,
choose B<Allow MCP access to this tab> from the userscript menu and enter
the printed URL when prompted. Other tabs remain unexposed.
The broker supplies C<tabs>, C<execute> and C<add-element> tools, permission
prompts, cancellation and execution timeouts. See
L<mcp-webbrowser/USERSCRIPT INSTALLATION AND USE> for setup, compatibility
and the current ScriptCat discarded-tab limitation.
If the multibroker launches the browser broker, keep that child running
from startup so browser tabs can connect:
mcp-multibroker --stdio browser --- mcp-webbrowser --- --eager
=head1 HTTP TOKENS AND SERVER IDENTITY
For the ordinary bundled HTTP endpoints, a client can present an accepted
token in either of these ways:
POST /TOKEN/
POST / Authorization: Bearer TOKEN
URL tokens are path components, not browser cookies.
For another configured endpoint, C</TOKEN> prefixes that endpoint path.
The HTTP server also accepts C</TOKEN> and the corresponding bare path
without the final slash when the endpoint is configured with one. This
works around clients (observed with Claude) that drop the final slash
from a configured URL.
Managed tokens authenticate distinct users for saved permissions. Existing
rules without match.user still apply to every user.
To add a user and obtain their multibroker URL:
anyevent-mcp create-user chatgpt
mcp-multibroker --print-url=chatgpt
An implicit global C<default> user starts at generation 1. The program,
instance, user and generation derive its token; the program, instance and
master secret determine a stable port in 16384..32767. Revoke a user to
disable its token; create it again to rotate the generation. Losing the master secret changes
all derived credentials. Keep an existing C<[global]> secret when editing
other configuration.
To configure explicit tokens:
[instance code]
tokens = first-secret,second-secret
Replace those placeholders with actual unguessable URL-safe tokens.
Repeated C<--token> options replace the whole configured list and the
derived managed users. In this mode C<--print-url> lists all enabled
users; explicit tokens still print the first accepted token.
Vim editors, browser tabs, and reverse servers need the effective
C<connect_user> token (default C<default>), not an arbitrary named user's token.
If C<--print-url> disagrees with the client's URL, compare the name,
command-line overrides, user and configuration environment with the running
process. The command resolves configuration; it does not ask the running
server which URL it uses. A changed file needs a server restart.
An Origin allowlist restricts browser origins; it does not authenticate
clients. A CORS preflight can succeed without a token, while the MCP POST
still requires one. See L<AnyEvent::MCP::Server::HTTP/AUTHENTICATION> for
the low-level server interface.
=head1 CLIENT EXAMPLES
Client settings and command syntax evolve independently of this distribution.
These examples show the connection choices; consult the linked client
documentation if its interface differs. Replace illustrative paths and
credentials with your own.
=head2 OpenAI Codex CLI
For the first direct filesystem connection:
codex mcp add code -- \
mcp-fs --stdio --name code /home/alice/src/project
codex mcp list
For a multibroker connection:
codex mcp add mytools -- \
mcp-multibroker --stdio \
code 'stdio:mcp-fs --name code /home/alice/src/project'
lib/AnyEvent/MCP/Intro.pod view on Meta::CPAN
--log.format=struct-text \
--log.level=warn \
--control-plane.tunnel-id=tunnel_... \
--mcp.connection-max-ttl=120s \
--mcp.server-url=http://127.0.0.1:16586/TOKEN/
Replace C<TOKEN> with the actual URL path printed above, and keep it
private. In this mode, the multibroker must remain running separately;
the tunnel only connects to it. Both modes require the tunnel runtime
to remain active while the hosted client uses the server. Use B<one>
of C<--mcp.command> and C<--mcp.server-url>, not both.
In ChatGPT, add a custom MCP server using a Tunnel connection and select
the tunnel ID. Creation and visibility depend on the Platform and ChatGPT
workspace permissions. The tunnel client's CLI and supported configuration
forms can vary between releases; the examples above use the direct runtime
CLI rather than its optional profile setup. See
L<Secure MCP Tunnel|https://developers.openai.com/api/docs/guides/secure-mcp-tunnels>
for obtaining a tunnel, runtime, credentials and connecting it to ChatGPT.
=head1 TROUBLESHOOTING
=head2 The server does not start
Read stderr or the client's server log. Missing Perl modules, a missing
workdir, unsuitable utilities or an unavailable bubblewrap executable can
fail startup. Confirm that the client launches the same executable and
arguments you intended, with the expected C<PATH> and Perl installation.
For a local sandbox check, run from the project directory:
mcp-fs --exec-cmd workdir-read -- ls
This runs C<ls> with the named grants and trusted baseline mounts, without
MCP or saved permission rules. A failure here can identify a bubblewrap
or runtime problem. It does not test the client connection or approval UI.
C<--sandbox none> disables isolation and changes worker authority; it is
not a fix that preserves the same permission boundary.
=head2 The client cannot connect
For stdio, configure a command the client launches, rather than a URL.
A separately running stdio process is not the client's connection.
Do not put banners or diagnostics on stdout.
For HTTP, leave the server running and check its address and port.
C<--print-url> exits without starting it. Loopback binds accept local
connections only; hosted or remote clients need the appropriate route or
tunnel. An occupied port causes a listener error, so check the server log.
For reverse C<--connect> servers, check the connecting process's log as
well as the multibroker. C<https://> requires a certificate trusted by
the connecting process and a hostname matching the URL. A TLS error
stops that reverse server immediately; it does not retry with plaintext.
TCP connection refusal is retried for up to sixty attempts.
=head2 Authentication fails
Obtain the URL with the same name, bind/token overrides and configuration
environment as the running process. Use the complete path; the final
slash is optional for endpoints whose configured path ends in one.
A clean URL needs an accepted bearer token.
A multibroker child credential is not necessarily the upstream listener's
credential. C<--bearer> after a child pair and C<--token> before the pairs
configure different sides of the connection.
For IMAP OAuth2, obtaining an access token does not by itself prove that
IMAP authentication will work. Check the authorized browser account,
requested IMAP scope and saved C<user> name. Copy the complete redirected
address-bar URL after authorization, even when the browser displays an
unreachable loopback page.
If the server warns that it cannot save the master secret, another process
may derive a different token. Check write access to the global configuration.
Do not replace an existing secret simply to add a setting.
=head2 Connected, but there are no tools
Inspect the server's stderr for omitted utilities. mcp-fs's C<workdirs>
tool reports configuration even when a utility-dependent tool is absent.
For a multibroker, call C<discover-brokers> to see individual connection
errors, then C<list-tools> to refresh definitions.
A third-party child might require initialization or features this client
implementation does not support. See L<AnyEvent::MCP::Client> and its
transport documentation for limitations.
=head2 There is no approval dialog
First check whether the tool was denied by a saved rule or is waiting for
the client's own approval. An allowed operation needs no server prompt.
The default helper runs on the server machine. A background service may
have neither a usable display nor C</dev/tty>, even though your interactive
shell has both. Supply the appropriate display environment, a usable helper,
or C<--ask auto> with a modern client supporting form elicitation.
C<--ask mcp> reports an error if that support is absent.
Setting an asking mode cannot make an unsupported client display a form.
Check stderr and the tool error instead of assuming a missing dialog is
an approval.
=head2 It asks again after I chose allow
Allow-once covers one tool invocation, including its permission retries.
The next invocation asks again. Use allow-always to save a rule.
Inspect the saved rule's action, workdir and grants. Listing names and
reading contents are different actions. A rule for one exact workdir
spelling will not match a differently spelled startup argument.
A request for extra authority, such as networking, does not match a
workdir-read-only allow rule. Earlier ask or deny rules take precedence.
Confirm that the prompt's permanent rule was successfully saved and that
you are editing the rules for the actual child name, not merely its
multibroker prefix.
=head2 The worker cannot see a directory or executable
The worker sees granted mounts and trusted baseline mounts, not everything
( run in 0.791 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )