ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MCP/README
Revision: 1.8
Committed: Fri Oct 30 14:19:26 2026 UTC (3 weeks ago) by root
Branch: MAIN
CVS Tags: rel-0_7
Changes since 1.7: +11 -7 lines
Log Message:
0.7

File Contents

# User Rev Content
1 root 1.2 NAME
2     AnyEvent::MCP::Intro - using MCP servers, clients and permissions
3    
4     DESCRIPTION
5     You can use the servers in this distribution without writing any Perl.
6     This walkthrough starts with one filesystem server, connects it to an
7     MCP client, and makes a useful request. Once that works, it explains
8     persistent configuration, permissions and combining several servers.
9    
10     If you want to write a small server yourself, continue with "TUTORIAL"
11     in AnyEvent::MCP::Server::Simple. Applications needing their own
12     connection management or dispatch can use the modules described in
13     "MODULES" in AnyEvent::MCP.
14    
15     The examples use "/home/alice/src/project" as an existing project
16     directory. Replace it with your own absolute path. Commands shown here
17     are commands for you to run; requests addressed to the LLM are shown
18     separately.
19    
20     INSTALLATION
21     Install the Perl distribution and the external programs used by the
22     servers. Installing one does not install the other.
23    
24     For mcp-fs, install Linux bubblewrap and the filesystem utilities. On
25     Debian or Ubuntu, for example:
26    
27     sudo apt install bubblewrap findutils grep patch sed perl yad
28    
29     "yad" is optional: it supplies graphical permission dialogs. Without a
30     usable YAD dialog, the helper tries "/dev/tty"; if neither is available,
31     it denies the request. Bubblewrap's executable is "bwrap". The machine
32     must allow the unprivileged user namespaces it needs.
33    
34     mcp-fs detects its utilities at startup and omits tools whose utilities
35     are unavailable or unsuitable. It requires bubblewrap by default. See
36     "TRUSTED CONFIGURATION" in mcp-fs for explicit utility paths and
37     "LIMITATIONS" in mcp-fs for the sandbox's limits.
38    
39     If you have an unpacked distribution or source checkout, run these
40     commands in its top-level directory:
41    
42     perl Makefile.PL
43     make
44     make test
45     make install
46    
47     "perl Makefile.PL" reports missing Perl dependencies. Install those with
48     your usual package manager or CPAN client before continuing. For
49     example, the main non-core dependencies can be installed with:
50    
51 root 1.8 cpan AnyEvent AnyEvent::HTTP common::sense JSON::XS
52    
53     "mcp-webbrowser" requires "AnyEvent::WebSocket::Server" and
54     "AnyEvent::WebSocket::Message". "mcp-vim" needs them only for browser
55     connections, not for ordinary Vim clients. Both modules are recommended
56     rather than required by the distribution.
57 root 1.2
58     Use the same Perl installation for dependency installation, building and
59     running the servers. A module installed for the system Perl might not be
60     available to a Perl installed under "/opt". "make install" needs write
61     access to the selected Perl's installation directories; use an
62     appropriate local Perl installation or run that final step with the
63     required privileges.
64    
65     Installation puts "mcp-fs", "mcp-multibroker", "mcp-vim",
66     "mcp-webbrowser", "mcp-ask-user", "anyevent-mcp" and
67     "anyevent-mcp-askpermission" in the selected executable directory. Make
68     that directory available in the environment of your MCP client, or
69     configure absolute executable paths. A desktop application need not have
70     the same "PATH" as your shell.
71    
72     To try an uninstalled source tree after installing its dependencies, you
73     can run a program with the source library path:
74    
75     perl -Ilib bin/mcp-fs --stdio --name code /home/alice/src/project
76    
77     Do this from the distribution directory. When configuring a client to
78     start such a command, account for the client's working directory or use
79     absolute paths to Perl, "lib" and the script. An installed executable
80     avoids that extra setup.
81    
82 root 1.3 PICK A SERVER
83     For a local MCP client, configure it to launch the server that provides
84     the tools you want:
85 root 1.2
86 root 1.3 mcp-fs --stdio /home/alice/src/project
87     mcp-vim --stdio
88 root 1.2 mcp-webbrowser --stdio
89 root 1.3 mcp-ask-user --stdio
90    
91     "--stdio" means the MCP client launches the process. Do not start a
92     separate copy in a terminal. For HTTP clients, use a running server and
93     its "--print-url" instead, as explained below.
94    
95     "mcp-fs" reads, searches and changes files and runs commands in a
96     sandbox. The first walkthrough below uses this server.
97    
98     "mcp-vim" reads and edits live Vim buffers. Install the companion Vim
99     plugin and connect the editor to its listener; see "Add a live Vim
100     editor" and "VIM PLUGIN INSTALLATION" in mcp-vim.
101    
102     "mcp-webbrowser" works with explicitly approved browser tabs. Install
103     its companion userscript and connect each tab you want to expose; see
104     "CONNECTED BROWSER PAGES".
105 root 1.2
106 root 1.3 "mcp-ask-user" lets the assistant ask you questions through a local YAD
107     or terminal dialog, or through the client's native form UI; see "Ask the
108     client's human a question".
109 root 1.2
110 root 1.4 To offer several servers over one MCP connection, use "mcp-multibroker".
111     It combines these servers with each other or with third-party MCP
112     servers, whether started locally over stdio or reached over HTTP. Their
113     tools appear under separate name prefixes; see "COMBINING SERVERS" and
114     mcp-multibroker for the full command syntax.
115 root 1.2
116     YOUR FIRST FILESYSTEM SERVER
117     Start with one project and one connection. You do not need a
118     multibroker, a hand-written configuration file or saved permission rules
119     yet.
120    
121     Choose stdio or HTTP
122     Use stdio when your MCP client runs on the same machine and can launch a
123     server process. Configure the client to start the following command:
124    
125     mcp-fs --stdio --name code /home/alice/src/project
126    
127     The client starts this process and uses its stdin/stdout for MCP. You do
128     not start a second copy in a terminal, and there is no listener URL or
129     HTTP token to configure. Diagnostics go to stderr.
130    
131     Clients that take a command and an argument array need these values:
132    
133     command: mcp-fs
134     arguments: --stdio, --name, code, /home/alice/src/project
135    
136     These describe separate arguments, not one shell command string. Use an
137     absolute executable path if the client cannot find "mcp-fs". See "CLIENT
138     EXAMPLES" for examples of particular clients.
139    
140     Use HTTP when the client connects to an already-running server, or when
141     it cannot launch a local process. Start this in a terminal on the server
142     machine and leave it running:
143    
144     mcp-fs --name code --bind :31741 /home/alice/src/project
145    
146     In another terminal, obtain the matching connection URL:
147    
148     mcp-fs --name code --bind :31741 --print-url
149    
150     The second command prints a credential-bearing URL and exits without
151     opening a listener. Configure that URL in the client. The default
152     address is IPv4 loopback, so this example is reachable from the same
153     machine only. A hosted client needs a suitable tunnel or reachable
154     endpoint; its own "localhost" is not your computer.
155    
156     Repeat the same name and listener overrides when printing the URL. Both
157     commands must use the same user and configuration directory. Port zero
158     chooses an ephemeral port, which "--print-url" cannot predict; use an
159     explicit port for this walkthrough.
160    
161     The HTTP server generates and saves its private master secret when
162     needed. You can initialize it explicitly with "anyevent-mcp init", but
163     that command is unnecessary when configuration already exists and will
164     refuse to replace it. Keep the printed URL private: possession of its
165     token authenticates a client.
166    
167     Make a useful request
168     Once your client reports that the server is connected, ask the LLM:
169    
170     Show me the configured workdirs. List the top-level files in the
171 root 1.3 project, then read its README if it has one. Do not modify files
172     or run commands.
173 root 1.2
174     "workdirs" returns the configured paths, sandbox grants, trusted mounts
175     and runtime paths. Listing names requests "inspect" permission; reading
176     contents requests "read" permission. Expect a permission prompt when
177     there is no saved rule allowing the operation.
178    
179     Choose "Allow once" for the first operation. The worker then runs with
180     the requested sandbox grants. A denial is a tool failure that the LLM
181     should report, rather than an empty file or a disconnected server.
182    
183     For a slightly larger task, ask:
184    
185     Find TODO comments in this project and explain the three that look
186     most useful to address next. Do not modify files or run commands.
187    
188     This can use "find", "grep" and "read-lines". You need not write MCP
189     requests yourself. If a client offers its own tool-approval prompt, that
190     is an additional client policy; it does not replace mcp-fs's
191     permissions.
192    
193 root 1.3 Give the server a purpose
194     To explain why an instance exists, provide a short purpose:
195    
196     mcp-fs --stdio --name memory \
197     --custom-instructions 'Use this server to retrieve and store persistent memory.' \
198     /home/alice/memory
199    
200     For persistent configuration, use "custom_instructions" in the global
201     configuration's "[program mcp-fs]" or "[instance memory]" section.
202     Instance settings override program settings; the command line overrides
203     both. This purpose appears first in the advertised MCP instructions so a
204     model can decide whether to discover the server's tools.
205    
206     Servers using "AnyEvent::MCP::Server::Simple" also expose the instance
207     purpose and complete operating instructions as a "meta-instructions"
208     tool description. Calling that tool returns the complete text when a
209     client truncates descriptions. Clients that understand MCP server
210     instructions still receive a short purpose or routing hint at discovery
211     time, followed by an automatic pointer to the full instructions in the
212     tool description.
213    
214 root 1.2 Understand the workdir
215     The directory passed at startup tells mcp-fs which workdir to expose. It
216     does not grant permission for every operation in that directory. Each
217     operation still requests its action and sandbox grants.
218    
219     With one workdir, tools can omit the "workdir" argument. With several:
220    
221     mcp-fs --stdio --name code /home/alice/src/project /home/alice/notes
222    
223     tools select one using a persistent positive integer ID, a numeric
224     string or an exact configured/resolved path returned by "workdirs". The
225     "workdirs" and "resolved_workdirs" objects use these IDs as keys.
226     Relative tool paths are relative to that selection. Permission rules
227     continue to use the configured path, not its numeric ID.
228    
229     IDs are shared across filesystem servers in
230     "$XDG_CONFIG_HOME/anyevent-mcp/fs-workdir-ids.json", or under
231     "$HOME/.config" by default. They identify resolved absolute paths and
232     survive restarts and argument reordering. Startup resolves IDs once and
233     reserves new allocations under the lock. A timer runs immediately and
234     every 5.25 days to reread the registry and refresh the server's fixed
235     assignments. Other entries expire after seven days and their IDs may be
236     reused. Restart servers after manually changing the registry.
237    
238     "workdir-read" exposes the selected workdir read-only. "workdir-write"
239     makes it writable and implies read access. A path in another configured
240     workdir requires all-workdirs authority; a path elsewhere requires
241     suitable home/world or shared-tmp authority. A symlink cannot make an
242     unmounted target appear inside the sandbox.
243    
244     Prefer separate, non-overlapping workdirs. Overlapping mounts have
245     unspecified access effects. See "SANDBOX GRANTS" in mcp-fs before
246     granting access beyond the selected workdir.
247    
248     Inspect version-control changes
249     For a Git, SVN, CVS or Mercurial working copy, ask the LLM to use
250     "vcs-diff" and "vcs-status", with "backend" set to "git", "svn", "cvs"
251     or "hg". "workdirs" reports the available clients. These tools accept
252     filenames and construct the command themselves; no shell pipeline or
253     arbitrary VCS options need to be approved.
254    
255     For example:
256    
257     Show the CVS diff for this project, limited to 200 lines.
258     Then show its status, keeping stdout lines matching "File:|Status:".
259    
260     These operations have their own permission actions. They request read
261 root 1.3 access to the selected workdir. CVS additionally requests the
262     "ssh-agent" grant, which includes network access, the agent socket and
263     "known_hosts", but not general home-directory access. Read permission
264     for ordinary file tools does not automatically authorize a VCS
265     operation.
266 root 1.2
267     For arbitrary "exec" commands, the same output options are available:
268     "grep" filters stdout using PCRE, "max_lines" limits matching stdout
269     lines, and "max_bytes" bounds returned bytes per stream. Prefer these
270     options to a shell wrapper that mixes execution and output processing.
271     Stderr is unfiltered, and exit status still describes the original
272     command.
273    
274     Defaults return at most 2000 stdout lines and 64 KiB per stream. Raw
275     capture has a separate 1 MiB limit per stream. A true
276     "capture_truncated" means output was omitted before filtering or
277     collection ended on timeout, so absent matches do not prove the omitted
278     output had none. See "Command output" in mcp-fs for all result flags and
279     limits.
280    
281     CONFIGURING YOUR SETUP
282     There are three different things to configure: how the client connects,
283     how the server runs, and which operations the user allows. Changing one
284     does not necessarily change the other two.
285    
286     Where each setting belongs
287     Directories to expose
288     Pass workdirs on the mcp-fs startup command. For a stdio server,
289     that command belongs in the client's server configuration. For an
290     HTTP server, it belongs in the command used to run the service.
291    
292     Connection transport
293     The client launches a command for stdio or connects to a URL for
294     HTTP. "--stdio" selects the former for mcp-fs and the multibroker.
295    
296     Listener address, port and tokens
297     Use "[instance NAME]" in the global configuration or command-line
298     "--bind" and "--token" overrides.
299    
300     Trusted mounts and utility paths
301     For mcp-fs, use "[program NAME]" defaults and "[instance NAME]"
302     overrides in the global configuration.
303    
304     Allowed operations and sandbox grants
305     Use the permission rules file, normally created through approval
306     dialogs. This file is separate from the global configuration.
307    
308     Location of permission prompts
309     Use "--ask helper", "--ask tty", "--ask yad", "--ask auto" or "--ask
310     mcp", or set "PERL_ANYEVENT_MCP_PERMISSION_ASK" in the server's
311     environment.
312    
313     Combined server connections
314     Put prefix/server pairs on the multibroker startup command. HTTP
315     child credentials can also use "[client PREFIX]" in the global
316     configuration.
317    
318     One complete named configuration
319     The global file is "$XDG_CONFIG_HOME/anyevent-mcp/global.ini", falling
320     back to "$HOME/.config/anyevent-mcp/global.ini". Settings are UTF-8 "key
321     = value" lines; values are unquoted. Whole-line "#" and ";" comments are
322     allowed. See "GLOBAL CONFIGURATION" in AnyEvent::MCP for the complete
323     format.
324    
325     Start with the existing file, preserving its "[global]" secret. If you
326 root 1.3 have no file yet, "anyevent-mcp init" creates it privately. Add this
327     section:
328 root 1.2
329     [instance code]
330     bind = 127.0.0.1:31741
331    
332     Now start:
333    
334     mcp-fs --name code /home/alice/src/project
335    
336     and retrieve its URL with:
337    
338     mcp-fs --name code --print-url
339    
340     Both use "[instance code]". No explicit token is needed: the server
341     derives one from its name and the existing master secret.
342    
343     For this setup:
344    
345     instance settings: [instance code]
346     selected workdir: /home/alice/src/project
347     permission file: ~/.config/anyevent-mcp/rules/fs-code.ini
348     rule-manager profile: fs-code
349    
350     The permission pathname above assumes the default configuration
351     directory. "anyevent-mcp manage-rules fs-code" opens the graphical rule
352     manager; "anyevent-mcp edit-rules fs-code" opens the file in your
353     editor.
354    
355 root 1.3 Settings shared by all mcp-fs instances go in "[program mcp-fs]".
356     Instance settings override program settings.
357    
358 root 1.6 File ownership and permissions are under the user's control. The global
359     configuration contains a master authentication secret, so take care when
360     sharing it. "--config FILE" on "anyevent-mcp init" selects that
361     command's output file; it does not make the servers use an arbitrary
362     alternate file. Use the same "HOME"/"XDG_CONFIG_HOME" environment when
363     running the server and its management commands.
364 root 1.2
365     Names, prefixes and profiles
366     "--name code" selects instance settings, derived HTTP credentials and
367     mcp-fs's "rules/fs-code.ini". Without "--name", mcp-fs uses "default",
368     giving profile "fs-default". Two processes with the same program, name
369     and configuration share credentials and rules, even if their workdirs
370     differ.
371    
372     A multibroker prefix, such as "files", only routes tools: "grep" becomes
373     "files.grep". It does not rename the child server or select its rules.
374     For example:
375    
376     mcp-multibroker files \
377     'stdio:mcp-fs --name code /home/alice/src/project'
378    
379     The tools are "files.*", but the child still uses instance "code" and
380     rule-manager profile "fs-code". The multibroker's own "--name" selects
381     its upstream listener settings.
382    
383     Configuration changes and restarts
384     Command-line listener options override the named global settings. For
385     mcp-fs trusted settings, an instance entry overrides the corresponding
386     program entry; an empty instance mount value suppresses the inherited
387     mount.
388    
389     Workdirs, mounts, utility paths, listener settings and tokens are read
390     at startup. Change the file or startup command, then restart the
391     affected server. The multibroker also needs restarting to change its
392     prefix/server pairs; refreshing discovery does not change those pairs.
393    
394     Permission rules are reread on permission checks, so editing them does
395     not require a restart. A client's displayed tool list can still be
396     cached. After restarting a child, refresh tool discovery or reconnect
397     the client as described in "COMBINING SERVERS".
398    
399     PERMISSIONS IN PRACTICE
400     HTTP authentication establishes that the client may connect. Permission
401     checks decide whether a tool may perform an operation. A correct token
402     therefore does not prevent permission prompts.
403    
404     What the prompt means
405     The prompt describes an action, paths or command, a reason and sandbox
406     grants. For filesystem tools, the actions are:
407    
408     inspect stat, list, find
409     read file-read, read-lines, grep
410     write file-write, file-patch
411     manage path-op
412     exec arbitrary command execution
413     vcs-diff working-copy differences
414     vcs-status working-copy status
415    
416     The action and grants are independent. Allowing "read" does not allow
417     "write", even if a worker grant permits both kinds of filesystem access.
418     "exec" runs arbitrary commands; it is not a classification of supposedly
419     safe command prefixes.
420    
421     Choose allow/deny once, or always. Closing the dialog denies once. An
422     optional denial reason is returned with the error; it is not added to
423     successful tool results. An always choice opens a rule editor. Choose an
424     indefinite lifetime (the default), 900 seconds or 16 hours. Finite
425     lifetimes are stored as "expires" Unix timestamps. Expired rules
426     disappear on every read; the next ordinary save removes them from disk.
427     Expiry affects future permission checks, not operations already
428     authorized. Filesystem allow rules can select grants and the selected
429     workdir when the authority depends on it. Deny rules can also select an
430     exact affected path. Exec offers persistent command/argv subjects.
431    
432     For exec, "View stdin..." lets you inspect supplied input without
433     closing the approval dialog. Filesystem and Vim patch tools similarly
434     offer "View patch...", including the target file or editor and buffer.
435     Longer text is shown as an explicitly incomplete preview. These are YAD
436     button labels; other interfaces can show the details inline. That input
437     is display-only: an exec allow rule does not constrain future stdin.
438     Allowing an interpreter command can therefore allow a different script
439     on its next invocation.
440    
441     A worker accessing several paths requests their combined sandbox
442     authority once. If the chosen grants are insufficient, it fails before
443     starting.
444    
445     Save a useful read-only policy
446     After trying individual operations, you might want the LLM to inspect
447     and read the project without asking each time, while keeping changes
448     subject to approval. Put these rules in "rules/fs-code.ini", or create
449     equivalent allow rules through the prompt:
450    
451     [rule]
452     decision=allow
453     action=inspect
454 root 1.8 match.workdir=/home/alice/src/project
455 root 1.2 sandbox-grants=workdir-read
456    
457     [rule]
458     decision=allow
459     action=read
460 root 1.8 match.workdir=/home/alice/src/project
461 root 1.2 sandbox-grants=workdir-read
462    
463     [rule]
464     decision=deny
465     action=exec
466    
467     Use the exact workdir spelling passed at server startup. Absolute
468 root 1.6 startup paths make this easier. Rule-file permissions follow the usual
469     Unix filesystem rules; any user who can edit the file can change the
470     server's approval policy.
471    
472     Without matching rules, write and manage operations still ask. The final
473     rule denies command execution outright; omit it if you want execution to
474     ask instead.
475 root 1.2
476     Rules run in order, stopping at the first match. An allow rule matches
477     only when its grants cover the request, including implications.
478     "workdir-write" implies "workdir-read"; "network" remains independent.
479 root 1.8 Action and "match.NAME" match exactly unless beginning with "^", which
480     selects a Perl regular expression; workdir scopes use the same
481     mechanism. An explicit "ask" rule can override later allow rules.
482 root 1.2
483     These allow rules authorize sandbox access to the selected workdir. They
484     cannot confine authority to one file or a subtree inside it. Filesystem
485     operations do not offer persistent path subjects. An exact "path"
486     matcher is available for deny rules only. Trusted runtime and configured
487     mounts remain baseline access independently of these grants. See
488     "TRUSTED CONFIGURATION" in mcp-fs.
489    
490     Change or remove saved rules
491     Use:
492    
493     anyevent-mcp manage-rules fs-code
494     anyevent-mcp edit-rules fs-code
495    
496     The first command lets you delete and reorder rules in YAD. The second
497     uses $VISUAL, $EDITOR, "sensible-editor" or "vi". An earlier deny or ask
498     rule can explain why adding a later allow rule does not change the
499     result.
500    
501     For a custom application with another rule pathname, use:
502    
503     anyevent-mcp manage-rules-file /path/to/rules.ini
504     anyevent-mcp edit-rules-file /path/to/rules.ini
505    
506     A failed attempt to save a permanent rule is an error, not a successful
507 root 1.6 permanent approval. The file mode is preserved when saved through these
508     commands. For full syntax and programming interfaces, see
509 root 1.2 AnyEvent::MCP::Server::Permissions.
510    
511     Choose where to ask
512     The default "helper" mode runs "anyevent-mcp-askpermission" on the
513     server machine. It tries YAD, then "/dev/tty", then denies if neither
514     can be used. The helper inherits the server's display environment.
515     "--ask tty" and "--ask yad" instead force the built-in terminal or YAD
516     interface. They ignore custom helper settings and never try another
517     interface. These modes work for permission prompts and ordinary forms,
518     including forms handled by a multibroker.
519     "PERL_ANYEVENT_MCP_PERMISSION_HELPER" selects a different executable.
520    
521     For a modern client supporting MCP form elicitation, you can instead
522     use:
523    
524     mcp-fs --stdio --name code --ask auto /home/alice/src/project
525    
526     "auto" uses the client's form support when advertised for that request,
527     otherwise the local helper. "mcp" requires that support and fails when
528     unavailable. It does not silently fall back. Use client-side permission
529     approval only when that client is a trusted authority to grant access.
530    
531     To set the default for servers using the shared permission engine:
532    
533     PERL_ANYEVENT_MCP_PERMISSION_ASK=auto \
534     mcp-fs --stdio --name code /home/alice/src/project
535    
536     An explicit application "ask" setting or "--ask" overrides the
537     environment. For spawned stdio children, "mcp-multibroker --ask auto"
538     passes this default to them. It cannot change the environment of an
539     independently running HTTP server.
540    
541     The multibroker can handle form elicitation locally for both stdio and
542     HTTP children. "--ask helper" selects local dialogs even if the upstream
543     client advertises native forms; "--ask mcp" forwards forms upstream, and
544     "auto" uses native forms when advertised. If a client claims support but
545     silently declines questions, use "helper". A decline never causes a
546     fallback prompt.
547    
548     Standalone "mcp-ask-user" also supports these modes and defaults to the
549     local helper. A question is different from an approval: answering it
550     does not grant a filesystem worker any authority.
551    
552     COMBINING SERVERS
553 root 1.4 Once the first connection works, "mcp-multibroker" lets you give the
554     client one connection for several MCP servers. It works with the servers
555     in this distribution and with third-party MCP servers, including ones
556     written in other languages. Each downstream server can be a local
557     subprocess communicating over stdio or an existing HTTP endpoint; you
558     can mix both in one broker. The broker discovers their tools and
559     forwards calls to the appropriate server without changing how that
560     server implements its tools.
561    
562     For example, combine two filesystem instances:
563 root 1.2
564     mcp-multibroker --name tools --bind :31740 \
565     code 'stdio:mcp-fs --name code /home/alice/src/project' \
566     notes 'stdio:mcp-fs --name notes /home/alice/notes'
567    
568     Quote each "stdio:" shell command as one argument. The broker supplies
569     the child's stdio environment and starts ordinary children lazily, on
570     first use. The explicit child names give them separate permission
571     profiles "fs-code" and "fs-notes".
572    
573     Obtain the upstream HTTP URL with:
574    
575     mcp-multibroker --name tools --bind :31740 --print-url
576    
577     Configure this URL in place of the client's old direct connection. The
578     client can now see "code.grep", "code.read-lines", "notes.find" and
579     other prefixed tools. It does not need a separate connection to each
580     child.
581    
582     For a client launching the multibroker locally, configure:
583    
584     mcp-multibroker --stdio --name tools \
585     code 'stdio:mcp-fs --name code /home/alice/src/project' \
586     notes 'stdio:mcp-fs --name notes /home/alice/notes'
587    
588     "--stdio" selects the upstream connection. The child commands still use
589     "stdio:"; that selects each downstream connection independently. No
590     upstream HTTP URL is needed in this case.
591    
592 root 1.4 The same setup can include Vim, browser pages, a third-party stdio
593     server or a remote HTTP service. See "Add an HTTP child" for an example
594     mixing local and remote servers, and "DOWNSTREAM SERVERS" in
595     mcp-multibroker for the complete syntax, including direct argv
596     execution, credentials and per-child options.
597    
598 root 1.2 Discover and refresh tools
599     Ask the LLM:
600    
601     Call discover-brokers and list-tools, then show me which servers
602     are available and what each is for.
603    
604 root 1.3 "discover-brokers" returns advertised instructions (which may be short),
605     no instructions, or an error for each configured server. "list-tools"
606     requests current tool definitions, including any prefixed
607     "meta-instructions" tools and their full instruction descriptions;
608     unreachable servers are omitted. A reachable server can still fail
609     later.
610 root 1.2
611     If the client still has an old direct tool list, "call-tool" can invoke
612     an exact prefixed name found by "list-tools". Refresh the client's MCP
613     connection if it continues to hide newly available tools.
614    
615     Discovery queries configured servers and currently registered reverse
616     connections. Changing the static downstream command still requires a
617     restart.
618    
619     Let a server connect to the multibroker
620     To add independently started servers without editing the multibroker
621     command, keep its HTTP/extension listener active alongside stdio:
622    
623     mcp-multibroker --stdio --listen --bind 127.0.0.1:31740
624     mcp-multibroker --bind 127.0.0.1:31740 --print-url
625    
626     Append an alias to the returned credential-bearing URL:
627    
628     mcp-fs --connect http://127.0.0.1:31740/TOKEN/files /home/alice/project
629    
630     The filesystem server initiates the TCP connection but remains the MCP
631     server. The multibroker authenticates the same token used for HTTP,
632     registers the alias and discovers the tools. A configured or connected
633     alias cannot be replaced. After disconnecting, the server retries once
634     per second for sixty attempts. Pending calls fail and are never
635     replayed. Remote registration does not grant the multibroker
636     spawned-child shutdown authority.
637    
638     The hello is a raw JSON line, followed by ordinary MCP JSONL on the same
639     socket; the HTTP-shaped URL is an address and credential, not an HTTP
640     request. The bundled connector supports plain "http://" endpoints. An
641     HTTP listener is already active by default when the upstream connection
642     is HTTP.
643    
644     Add an HTTP child
645 root 1.4 A broker can mix spawned stdio servers and existing HTTP endpoints,
646     including independently implemented third-party servers:
647 root 1.2
648     mcp-multibroker --stdio \
649     code 'stdio:mcp-fs --name code /home/alice/src/project' \
650     remote https://example.org/mcp/ --bearer TOKEN
651    
652     "--bearer" immediately after the HTTP pair belongs to that child.
653     "--token" before all pairs configures the multibroker's own HTTP
654     listener. They authenticate different connections.
655    
656     To avoid putting a child's bearer token in the startup command, add:
657    
658     [client remote]
659     bearer = TOKEN
660     timeout = 300
661    
662     to the private global configuration, and omit "--bearer" from the
663     command. The prefix "remote" selects these client defaults. The
664     command-line URL still chooses the endpoint. Use the actual credential
665     accepted by that server, not the literal placeholder "TOKEN".
666    
667     A token already present in a child's URL needs no separate bearer
668     option. The bundled servers use static URL-safe tokens; they do not
669     validate OAuth access tokens or implement HTTP Basic authentication. Use
670     TLS or an appropriate tunnel when credentials cross untrusted networks.
671    
672     The multibroker does not put every child inside the mcp-fs sandbox. Each
673     process or remote service has its own authority and enforcement.
674    
675     Add a live Vim editor
676     Install the Vim plugin using "VIM PLUGIN INSTALLATION" in mcp-vim. It is
677     included in the source distribution but is not installed by Perl's "make
678     install".
679    
680 root 1.3 Without a multibroker, configure the MCP client to launch:
681    
682     mcp-vim --stdio --name editor
683    
684     Even in stdio mode, mcp-vim listens separately for editor connections.
685     If using a multibroker, start its child eagerly so Vim can connect
686     before the first MCP tool call:
687 root 1.2
688     mcp-multibroker --stdio \
689     code 'stdio:mcp-fs --name code /home/alice/src/project' \
690     vim 'stdio:mcp-vim --name editor' --eager
691    
692 root 1.3 In another terminal, obtain the editor broker's URL prefix:
693 root 1.2
694     mcp-vim --name editor --print-url
695    
696     Append the desired target name in Vim:
697    
698     :Mcp http://HOST:PORT/TOKEN/my-editor
699    
700     Use the actual printed prefix in place of "http://HOST:PORT/TOKEN/". Ask
701 root 1.3 the LLM to call "targets", then "state" before reading or editing
702     buffers ("vim.targets" and "vim.state" through the multibroker). These
703     tools see live, possibly unsaved buffers. Edits require a current
704     changedtick and do not save files to disk.
705 root 1.2
706     To pass arguments directly, use "PREFIX --- PROGRAM ARG... ---":
707    
708     mcp-multibroker --stdio \
709     vim --- mcp-vim --name editor --bind :: --- --eager \
710     code --- mcp-fs --name code '/home/alice/project with spaces' ---
711    
712     Only the invoking shell processes quoting. The broker passes all
713     arguments between the delimiters unchanged, including empty arguments
714     and child options. Use "stdio:COMMAND" for shell syntax or a literal
715     "---" child argument. An empty command or missing closing delimiter is
716     an error.
717    
718     "--eager" belongs immediately after its stdio URL or closing "---". An
719     eager connection failure is logged; the broker does not continuously
720     restart the child. Later tool use can try connecting again.
721    
722     Ask the client's human a question
723 root 1.3 To let the assistant ask you questions, configure its MCP client to
724     launch:
725    
726     mcp-ask-user --stdio
727    
728     Or add the question server to a multibroker:
729 root 1.2
730     mcp-multibroker --stdio \
731     code 'stdio:mcp-fs --name code /home/alice/src/project' \
732     questions 'stdio:mcp-ask-user'
733    
734 root 1.3 The LLM can call "ask-user" ("questions.ask-user" through the
735     multibroker) with a question, up to three suggested answers and room for
736     free text. For example, tell it to use that tool if choosing among
737     several possible tasks needs your input. For several fields or other
738     value types, "ask-form" ("questions.ask-form" through the multibroker)
739     accepts "message" and "requestedSchema" directly and returns the
740     standard elicitation response. Both tools use the same configured
741     presentation mode. Decline and cancel are distinct results; neither
742     supplies an answer.
743 root 1.2
744     By default the multibroker displays questions locally, using YAD or a
745     terminal. Add "--ask mcp" before the broker entries to use the client's
746     native forms, or "--ask auto" to select by advertised capability. This
747     also works with "mcp-ask-user" started separately: give that server
748     "--ask mcp" so it delegates presentation to its connecting multibroker.
749    
750     "anyevent-mcp-form-elicitation" is the standalone form renderer. It
751     reads standard MCP form parameters as UTF-8 JSON on stdin and writes an
752     accept/decline/cancel response as JSON on stdout.
753     "PERL_ANYEVENT_MCP_ELICITATION_HELPER" selects a replacement executable.
754     See anyevent-mcp-form-elicitation for supported fields and mcp-ask-user
755     for question arguments and result fields.
756    
757 root 1.3 CONNECTED BROWSER PAGES
758     "mcp-webbrowser" is the browser-page counterpart to "mcp-vim". It
759     exposes only tabs explicitly allowed by the browser user. Configure your
760     MCP client to launch:
761    
762     mcp-webbrowser --stdio
763    
764     The broker keeps its own HTTP/WebSocket listener active even in stdio
765     mode; the userscript connects to that listener, not to MCP's stdio
766     stream. In a separate terminal, obtain its URL:
767    
768     mcp-webbrowser --print-url
769    
770     Use the same instance name and configuration as the broker. Keep this
771     credential-bearing URL private. Install the companion userscript from
772     "webbrowser/mcp-webbrowser.user.js" in the source distribution or from
773     <https://dist.schmorp.de/mcp-webbrowser/1/mcp-webbrowser.user.js>.
774     Chromium with ScriptCat has been tested. On a tab you want to expose,
775     choose Allow MCP access to this tab from the userscript menu and enter
776     the printed URL when prompted. Other tabs remain unexposed.
777    
778 root 1.5 The broker supplies "tabs", "execute" and "add-element" tools,
779 root 1.3 permission prompts, cancellation and execution timeouts. See "USERSCRIPT
780     INSTALLATION AND USE" in mcp-webbrowser for setup, compatibility and the
781     current ScriptCat discarded-tab limitation.
782    
783     If the multibroker launches the browser broker, keep that child running
784     from startup so browser tabs can connect:
785    
786     mcp-multibroker --stdio browser --- mcp-webbrowser --- --eager
787    
788 root 1.2 HTTP TOKENS AND SERVER IDENTITY
789     For the ordinary bundled HTTP endpoints, a client can present an
790     accepted token in either of these ways:
791    
792     POST /TOKEN/
793     POST / Authorization: Bearer TOKEN
794    
795     URL tokens are path components, not browser cookies. For another
796 root 1.7 configured endpoint, "/TOKEN" prefixes that endpoint path. The HTTP
797     server also accepts "/TOKEN" and the corresponding bare path without the
798     final slash when the endpoint is configured with one. This works around
799     clients (observed with Claude) that drop the final slash from a
800     configured URL. All accepted tokens authenticate the same operations;
801     they are not separate users or permission levels. Permissions still
802     govern the tool operation.
803 root 1.2
804     By default, the master secret and server name determine one stable token
805     and a port in 16384..32767. Changing a server's name changes its derived
806     credentials and default port. Changing or losing the master secret
807     changes all derived credentials. Keep an existing "[global]" secret when
808     editing other configuration.
809    
810     To configure explicit tokens:
811    
812     [instance code]
813     tokens = first-secret,second-secret
814    
815     Replace those placeholders with actual unguessable URL-safe tokens.
816     Repeated "--token" options replace the whole configured list and the
817     derived default. The first token appears in "--print-url"; all are
818     accepted. mcp-vim also accepts its token set for Vim and browser
819     WebSocket connections.
820    
821     If "--print-url" disagrees with the client's URL, compare the name,
822     command-line overrides, user and configuration environment with the
823     running process. The command resolves configuration; it does not ask the
824     running server which URL it uses. A changed file needs a server restart.
825    
826     An Origin allowlist restricts browser origins; it does not authenticate
827     clients. A CORS preflight can succeed without a token, while the MCP
828     POST still requires one. See "AUTHENTICATION" in
829     AnyEvent::MCP::Server::HTTP for the low-level server interface.
830    
831     CLIENT EXAMPLES
832     Client settings and command syntax evolve independently of this
833     distribution. These examples show the connection choices; consult the
834     linked client documentation if its interface differs. Replace
835     illustrative paths and credentials with your own.
836    
837     OpenAI Codex CLI
838     For the first direct filesystem connection:
839    
840     codex mcp add code -- \
841     mcp-fs --stdio --name code /home/alice/src/project
842     codex mcp list
843    
844     For a multibroker connection:
845    
846     codex mcp add mytools -- \
847     mcp-multibroker --stdio \
848     code 'stdio:mcp-fs --name code /home/alice/src/project'
849    
850     Use "/mcp" within Codex to inspect connections. See Codex MCP
851     documentation <https://learn.chatgpt.com/docs/extend/mcp>.
852    
853     Anthropic Claude Code
854     For the direct connection:
855    
856     claude mcp add --transport stdio --scope user code -- \
857     mcp-fs --stdio --name code /home/alice/src/project
858     claude mcp list
859    
860     Replace the launched command with the multibroker command above when you
861     want several servers. Use "/mcp" for connection status. See Claude Code
862     MCP documentation <https://code.claude.com/docs/en/mcp>.
863    
864     Google Gemini CLI
865     Merge a direct server entry into "~/.gemini/settings.json":
866    
867     {
868     "mcpServers": {
869     "code": {
870     "command": "mcp-fs",
871     "args": [
872     "--stdio", "--name", "code", "/home/alice/src/project"
873     ]
874     }
875     }
876     }
877    
878     For a combined connection, use "mcp-multibroker" as the command and its
879     "--stdio" and prefix/server pairs as the argument array. Use "/mcp" to
880     inspect the connection. See Gemini CLI MCP documentation
881     <https://geminicli.com/docs/tools/mcp-server/>.
882    
883     Hosted clients, including ChatGPT web
884     A hosted client cannot spawn your local stdio command or reach your
885 root 1.5 machine's loopback address directly. A Secure MCP Tunnel runs locally,
886     connects out to OpenAI, and forwards MCP requests to a local stdio
887     command or HTTP URL. No public listener or inbound firewall port is
888     needed.
889    
890     First create a tunnel in OpenAI Platform tunnel settings and obtain its
891     "tunnel_..." ID and a runtime API key. Arrange for
892     "CONTROL_PLANE_API_KEY" to be set securely in the tunnel client's
893     environment; do not put a real key in a script, command line or example.
894     Associate the tunnel with the ChatGPT workspace where you want to use
895     it.
896    
897     For stdio, put the server startup command in a small executable wrapper,
898     for example "/home/alice/bin/my-mcp":
899    
900     #!/bin/sh
901     exec mcp-multibroker --stdio \
902     code --- mcp-fs --name code /home/alice/src/project --- \
903     questions --- mcp-ask-user ---
904    
905     With a tunnel installation providing "tunnel-client-runtime", run:
906    
907     tunnel-client-runtime run \
908     --log.format=struct-text \
909     --log.level=warn \
910     --control-plane.tunnel-id=tunnel_... \
911     --mcp.connection-max-ttl=120s \
912     --mcp.command=/home/alice/bin/my-mcp
913    
914     The tunnel starts the wrapper as its stdio MCP server. Do not start a
915     separate copy yourself. Make the wrapper executable and ensure its
916     programs and Perl modules are on the tunnel process's "PATH".
917 root 1.2
918 root 1.5 For HTTP, instead start the server or multibroker separately:
919    
920     mcp-multibroker --name tools --bind 127.0.0.1:16586 \
921     code 'stdio:mcp-fs --name code /home/alice/src/project'
922    
923     Obtain the matching credential-bearing URL:
924    
925     mcp-multibroker --name tools --bind 127.0.0.1:16586 --print-url
926    
927     Then point the tunnel runtime at that URL, rather than a command:
928    
929     tunnel-client-runtime run \
930     --log.format=struct-text \
931     --log.level=warn \
932     --control-plane.tunnel-id=tunnel_... \
933     --mcp.connection-max-ttl=120s \
934     --mcp.server-url=http://127.0.0.1:16586/TOKEN/
935    
936     Replace "TOKEN" with the actual URL path printed above, and keep it
937     private. In this mode, the multibroker must remain running separately;
938     the tunnel only connects to it. Both modes require the tunnel runtime to
939     remain active while the hosted client uses the server. Use one of
940     "--mcp.command" and "--mcp.server-url", not both.
941    
942     In ChatGPT, add a custom MCP server using a Tunnel connection and select
943     the tunnel ID. Creation and visibility depend on the Platform and
944     ChatGPT workspace permissions. The tunnel client's CLI and supported
945     configuration forms can vary between releases; the examples above use
946     the direct runtime CLI rather than its optional profile setup. See
947 root 1.2 Secure MCP Tunnel
948 root 1.5 <https://developers.openai.com/api/docs/guides/secure-mcp-tunnels> for
949     obtaining a tunnel, runtime, credentials and connecting it to ChatGPT.
950 root 1.2
951     TROUBLESHOOTING
952     The server does not start
953     Read stderr or the client's server log. Missing Perl modules, a missing
954     workdir, unsuitable utilities or an unavailable bubblewrap executable
955     can fail startup. Confirm that the client launches the same executable
956     and arguments you intended, with the expected "PATH" and Perl
957     installation.
958    
959     For a local sandbox check, run from the project directory:
960    
961     mcp-fs --exec-cmd workdir-read -- ls
962    
963     This runs "ls" with the named grants and trusted baseline mounts,
964     without MCP or saved permission rules. A failure here can identify a
965     bubblewrap or runtime problem. It does not test the client connection or
966     approval UI. "--sandbox none" disables isolation and changes worker
967     authority; it is not a fix that preserves the same permission boundary.
968    
969     The client cannot connect
970     For stdio, configure a command the client launches, rather than a URL. A
971     separately running stdio process is not the client's connection. Do not
972     put banners or diagnostics on stdout.
973    
974     For HTTP, leave the server running and check its address and port.
975     "--print-url" exits without starting it. Loopback binds accept local
976     connections only; hosted or remote clients need the appropriate route or
977     tunnel. An occupied port causes a listener error, so check the server
978     log.
979    
980     Authentication fails
981     Obtain the URL with the same name, bind/token overrides and
982 root 1.7 configuration environment as the running process. Use the complete path;
983     the final slash is optional for endpoints whose configured path ends in
984     one. A clean URL needs an accepted bearer token.
985 root 1.2
986     A multibroker child credential is not necessarily the upstream
987     listener's credential. "--bearer" after a child pair and "--token"
988     before the pairs configure different sides of the connection.
989    
990     If the server warns that it cannot save the master secret, another
991 root 1.6 process may derive a different token. Check write access to the global
992     configuration. Do not replace an existing secret simply to add a
993     setting.
994 root 1.2
995     Connected, but there are no tools
996     Inspect the server's stderr for omitted utilities. mcp-fs's "workdirs"
997     tool reports configuration even when a utility-dependent tool is absent.
998     For a multibroker, call "discover-brokers" to see individual connection
999     errors, then "list-tools" to refresh definitions.
1000    
1001     A third-party child might require initialization or features this client
1002     implementation does not support. See AnyEvent::MCP::Client and its
1003     transport documentation for limitations.
1004    
1005     There is no approval dialog
1006     First check whether the tool was denied by a saved rule or is waiting
1007     for the client's own approval. An allowed operation needs no server
1008     prompt.
1009    
1010     The default helper runs on the server machine. A background service may
1011     have neither a usable display nor "/dev/tty", even though your
1012     interactive shell has both. Supply the appropriate display environment,
1013     a usable helper, or "--ask auto" with a modern client supporting form
1014     elicitation. "--ask mcp" reports an error if that support is absent.
1015    
1016     Setting an asking mode cannot make an unsupported client display a form.
1017     Check stderr and the tool error instead of assuming a missing dialog is
1018     an approval.
1019    
1020     It asks again after I chose allow
1021     Allow-once covers one tool invocation, including its permission retries.
1022     The next invocation asks again. Use allow-always to save a rule.
1023    
1024     Inspect the saved rule's action, workdir and grants. Listing names and
1025     reading contents are different actions. A rule for one exact workdir
1026     spelling will not match a differently spelled startup argument. A
1027     request for extra authority, such as networking, does not match a
1028     workdir-read-only allow rule. Earlier ask or deny rules take precedence.
1029    
1030     Confirm that the prompt's permanent rule was successfully saved and that
1031     you are editing the rules for the actual child name, not merely its
1032     multibroker prefix.
1033    
1034     The worker cannot see a directory or executable
1035     The worker sees granted mounts and trusted baseline mounts, not
1036     everything the server process can see. Check "workdirs" for the selected
1037     path, mounts and runtime paths. A symlink target outside those mounts is
1038     unavailable.
1039    
1040 root 1.3 The ordinary sandbox runtime includes "/usr", "/bin" and system
1041     libraries, but not "/opt". For tools or libraries under "/opt", add this
1042     to "[program mcp-fs]" in the private global configuration:
1043    
1044     mount.opt = ro:/opt
1045    
1046     This assumes "/opt" exists. Restart mcp-fs after changing trusted
1047     mounts. If your worker Perl is "/opt/bin/perl", you can also set
1048     "executable.perl = /opt/bin/perl" in that program section. Supply the
1049     actual executable path: selecting it does not itself mount the
1050     executable or its dependencies inside the worker.
1051    
1052     A trusted mount supplies baseline access to every worker using it; a
1053 root 1.2 writable mount likewise supplies baseline write authority.
1054    
1055     An arbitrary command might also need its user's configuration or
1056     repository credentials under HOME, or network access. Request the
1057     corresponding grants when needed; do not assume "workdir-read" includes
1058     them. For example, CVS over SSH can use "workdir-read" and "ssh-agent".
1059     The latter includes network access, the agent socket and
1060     "~/.ssh/known_hosts", without exposing private key files or the rest of
1061     HOME. The broker must inherit "SSH_AUTH_SOCK" from your environment.
1062     User-configured helpers outside the runtime mounts need an explicit
1063     trusted mount. An explicit exec grant array replaces the default rather
1064     than adding to it.
1065    
1066     My configuration change seems to be ignored
1067     Check which file and section the process actually selects. Global
1068     settings use the server user's "HOME"/"XDG_CONFIG_HOME". Instance names,
1069     program basenames and multibroker prefixes serve different purposes.
1070    
1071     Restart after changing startup settings, mounts or utilities. Permission
1072     rules need no restart, but their order still matters. Refresh discovery
1073     after a child restart; reconnect a client that retains an old tool list.
1074     "--print-url" reads the current configuration, which can differ from an
1075     older running process.
1076    
1077     The command failed, but the MCP request succeeded
1078     "exec" reports exit status, signal or timeout as a normal tool result. A
1079     successful MCP exchange is not a successful Unix command. Conversely, a
1080     transport failure does not prove a command did nothing: it may have
1081     completed before the connection was lost. Calls are not automatically
1082     replayed after a transport failure.
1083    
1084     TESTING
1085     The default test level is 0. It checks protocol behaviour, permissions,
1086     validation and ordinary process operation, including worker cancellation
1087     and reaping. Watchdogs allow slow machines time to finish; they do not
1088     make successful tests wait for the whole timeout.
1089    
1090     prove -Ilib t
1091    
1092     Set "PERL_ANYEVENT_MCP_TESTS" to 1 to include the extended tests:
1093    
1094     PERL_ANYEVENT_MCP_TESTS=1 prove -Ilib t
1095    
1096     Level 1 adds GNU find/grep/sed/patch operations, real Vim scripting,
1097     browser transfer integration, short idle-lifetime tests, a helper
1098     descendant holding a pipe open, and tests which deliberately wait for a
1099     command timeout or cancel a form helper across several processes. Run
1100     this level before releases. Values greater than 1 currently select the
1101     same tests as level 1.
1102    
1103     Missing GNU utilities or required Vim functions cause explicit skips
1104     even at level 1. The permission and form UI tests use a YAD stand-in:
1105     neither level requires YAD, X11 or an interactive display. The
1106     filesystem tests use a bubblewrap stand-in and check arguments and
1107     worker behaviour; they do not test kernel isolation. The browser tests
1108     use simulated peers.
1109    
1110     WHERE TO GO NEXT
1111     For available tools and server-specific options:
1112    
1113     perldoc mcp-fs
1114     perldoc mcp-multibroker
1115     perldoc mcp-vim
1116     perldoc mcp-ask-user
1117     perldoc anyevent-mcp
1118    
1119     For a complete first Perl server, options, replies, permission checks
1120     and asynchronous work, see "TUTORIAL" in AnyEvent::MCP::Server::Simple.
1121     For the module map and shared configuration reference, see
1122     AnyEvent::MCP. For permission rule details, see
1123     AnyEvent::MCP::Server::Permissions.
1124    
1125     SEE ALSO
1126     AnyEvent::MCP, AnyEvent::MCP::Server::Simple, mcp-fs, mcp-multibroker,
1127     mcp-vim, mcp-ask-user, AnyEvent::MCP::Server::Permissions
1128