ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/AnyEvent-MCP/README
Revision: 1.15
Committed: Fri Nov 20 01:54:37 2026 UTC (2 days, 16 hours ago) by root
Branch: MAIN
CVS Tags: HEAD
Changes since 1.14: +56 -39 lines
Log Message:
*** empty log message ***

File Contents

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