NAME
AnyEvent::MCP::Server::Simple - simple function interface for MCP servers
SYNOPSIS
use AnyEvent::MCP::Server::Simple;
mcp_config
server_name => "example",
server_version => 0,
instructions => <<'EOF';
Use echo to return the supplied text.
EOF
mcp_tool echo =>
"Return the supplied text.",
{
type => "object",
properties => { text => { type => "string" } },
required => ["text"],
},
sub {
my ($req, $args) = @_;
$req->reply ({
content => [{ type => "text", text => $args->{text} }],
});
};
mcp_start;
DESCRIPTION
For most MCP servers, registering a few tools and starting a transport is enough. This module does just that: call mcp_tool to register callbacks, optionally configure the server with mcp_config, then start it with mcp_start, mcp_stdio or mcp_http. Registration alone does not start a server or an event loop.
Human-readable descriptions and instructions are stripped of surrounding whitespace and common indentation when registered, so indented here-documents can be used naturally.
mcp_start, mcp_stdio and mcp_http are alternative blocking entry points for a self-contained server. They run AnyEvent until shutdown; you do not start another event loop. If your application already owns the server lifetime or needs several transports, use the object interfaces instead.
Simple uses AnyEvent::MCP::Server and a default Toolset internally; it is not a second server implementation. Applications needing custom dispatch, such as a multibroker, can use the Server API directly.
Start with "TUTORIAL" for a complete server and a first client call. For running the bundled servers without writing Perl, see AnyEvent::MCP::Intro.
TUTORIAL
This tutorial builds a small server, calls it, then adds options, permission checks and asynchronous work. You do not need to implement JSON-RPC, authentication or a transport. Simple supplies those parts; your program declares tools and handles their arguments.
For installation, connecting AI clients and configuring the bundled servers, see AnyEvent::MCP::Intro. The function reference follows this tutorial.
A complete first server
Save the following as echo-mcp:
#!/opt/bin/perl
use common::sense;
use AnyEvent::MCP::Server::Simple;
my $options = mcp_getoptions {
name => "echo-demo",
usage => "Usage: $0 [OPTION]...\n",
description => "Return text supplied to the echo tool.",
};
@ARGV == 0
or die "Unexpected arguments\n";
mcp_config
server_name => "echo-demo",
server_version => 1,
instructions => "Use echo to return the supplied text.";
mcp_tool echo =>
"Return the supplied text.",
{
type => "object",
properties => {
text => {
type => "string",
maxLength => 4096,
},
},
required => ["text"],
},
sub {
my ($req, $args) = @_;
my $text = $args->{text};
defined $text and !ref $text and length $text <= 4096
or die "text must be a string of at most 4096 characters\n";
$req->reply ({
content => [{ type => "text", text => $text }],
});
};
mcp_start %$options;
Use your installed Perl's explicit path in the shebang, or invoke the file with perl as in the commands below.
mcp_getoptions parses the common server options and returns startup settings. mcp_config declares protocol metadata and instructions. mcp_tool registers a description, input schema and callback. mcp_start constructs the transport and runs AnyEvent until shutdown. Register everything before starting: code after mcp_start runs only when the server stops.
The input schema tells the client what to supply. The server does not validate arguments against JSON Schema, so the callback checks the value it actually uses. A missing text, array or object fails as a tool error. The example allows an empty string.
$req is an AnyEvent::MCP::Server::Request; $args is its argument hash reference. Replying finishes the request. Merely returning from the callback does not. You supply the MCP result, and the server supplies the JSON-RPC envelope.
Start and call the server
Inspect the common options with:
perl echo-mcp --help
For a client launching a local subprocess, configure:
perl /absolute/path/to/echo-mcp --stdio
The client must launch the process itself. Stdin and stdout carry MCP, so starting the program in a terminal and typing text at it is not a test of the echo tool. Print diagnostics to stderr, not stdout.
You can make a first call without an AI client. Save this as try-echo in the same directory as echo-mcp:
use common::sense;
use AnyEvent;
use AnyEvent::MCP::Client::JSONL;
my $client = AnyEvent::MCP::Client::JSONL->new (
command => [$^X, "./echo-mcp", "--stdio"],
);
my $cv = AE::cv;
$client->call (echo => { text => "hello" }, sub {
$cv->send (@_);
});
my ($success, $result) = $cv->recv;
$success
or die "$result->{message}\n";
!$result->{isError}
or die "$result->{content}[0]{text}\n";
print $result->{content}[0]{text}, "\n";
Run perl try-echo. It prints:
hello
The JSONL client starts the server, connects and negotiates the protocol on first use. $^X chooses the same Perl interpreter as the test client. The condition variable keeps the event loop running until the reply arrives. Keep $client alive while its operations are outstanding.
There are two success checks. $success means the JSON-RPC operation completed successfully; a tool can still return isError in that result. This client expects our echo tool's text result. A general client must handle other MCP content representations too.
To use HTTP, start the server in one terminal:
perl echo-mcp --bind :31742
and retrieve its URL in another:
perl echo-mcp --bind :31742 --print-url
Configure that URL in your MCP client and ask it to call echo with text hello. Both commands use instance echo-demo, unless you override it with --name. Repeat the same listener overrides when printing the URL. --print-url prints the address and exits; it does not start a server.
For the small Perl client above, replace the JSONL import and constructor with:
use AnyEvent::MCP::Client::HTTP;
my $client = AnyEvent::MCP::Client::HTTP->new (
url => $ARGV[0],
);
Pass the printed URL as its first command-line argument. The rest of the call and result handling stays the same.
mcp_start supplies named HTTP settings and a token derived from the private global secret. Stdio needs no HTTP configuration. name selects local settings and credentials; server_name identifies the advertised MCP implementation. The two need not be the same. See "CONFIGURING YOUR SETUP" in AnyEvent::MCP::Intro.
Add an application option
Suppose you want the server user to choose the maximum text length. Replace the original mcp_getoptions call with:
my $max_length = 4096;
my $options = mcp_getoptions (
{
name => "echo-demo",
usage => "Usage: $0 [OPTION]...\n",
description => "Return text supplied to the echo tool.",
options => [
["--max-length N", "Maximum text length in characters"],
],
},
"max-length=i" => \$max_length,
);
$max_length > 0
or die "--max-length must be positive\n";
Use $max_length in both the schema's maxLength and the callback's length check. The server user can then start:
perl echo-mcp --stdio --max-length 1000
The option specification is passed to Getopt::Long. The options entries supply human-readable help; they do not register options. The later tool examples use the original 4096-character limit; use your chosen limit in them too if you keep this option. Common options such as --stdio, --bind and --help remain available.
If your server also takes positional arguments, validate the remaining @ARGV after mcp_getoptions. It handles --help and --print-url before that validation, so the user can retrieve an HTTP URL without supplying an application workdir or starting the application.
Settings affecting URL discovery, such as name and path, should be available to mcp_getoptions through its leading settings hash or an earlier mcp_config call. A setting supplied only after the parser exits for --print-url cannot affect that printed URL.
Choose a result representation
Our echo callback returns one text content item. Use reply when the representation matters: text, other content types, a larger result or a particular MCP result shape.
For an ordinary result object, you can replace the reply with:
$req->result ({ text => $text, length => length $text });
result returns that hash as structuredContent and also serializes it as JSON in one text content item. Clients consuming only text can still see the data, but it is deliberately duplicated. Wrap arrays or scalars in an object, or use reply to choose a different representation.
To report a tool failure explicitly:
$req->error ("The requested operation cannot be completed");
A synchronous exception from the handler also becomes a tool-error result. Malformed protocol requests and an unknown tool name are handled by the server. Your callback does not construct a JSON-RPC response itself.
Reply once. Code that calls reply, result or error and then calls another reply method is a programming error. Keep a final reply separate from the work leading to it so the completion point is easy to see.
Add a permission check before changing state
Authentication alone does not decide which tool operations a user allows. For an example with a side effect but no external worker, add a tool that stores one note in the server's memory.
Add this before registering the tools:
use AnyEvent::MCP::Server::Permissions;
my $note;
mcp_permissions +AnyEvent::MCP::Server::Permissions->new (
name => "echo-notes",
actions => {
remember => "Replace the server's in-memory note",
},
);
Then register this tool before mcp_start:
mcp_tool remember =>
"Replace the server's in-memory note with the supplied text.",
{
type => "object",
properties => {
text => { type => "string", maxLength => 4096 },
},
required => ["text"],
},
sub {
my ($req, $args) = @_;
my $text = $args->{text};
defined $text and !ref $text and length $text <= 4096
or die "text must be a string of at most 4096 characters\n";
$req->require_permission ({
tool => $req->{tool},
action => "remember",
sandbox_grants => [],
reason => "replace the server's in-memory note",
});
$note = $text;
$req->result ({ remembered => length $note });
};
Restart the server and call remember through your client. The default permission helper asks on the server machine. Allow once permits this invocation. Allow always saves a rule for action remember; subsequent matching calls do not ask again. The note itself lasts only for this server process and is shared by its clients.
The permission engine's name echo-notes selects its default policy file:
~/.config/anyevent-mcp/rules/echo-notes.ini
The actual directory follows XDG_CONFIG_HOME when set. This is the shared engine's default convention, different from mcp-fs's rules/fs-NAME.ini. Manage it using anyevent-mcp manage-rules-file with the actual pathname, or supply file to the engine explicitly.
For example, a manually written allow rule is:
[rule]
decision=allow
action=remember
sandbox-grants=
The empty grant list is intentional. This tool updates an in-memory value; it does not launch a sandboxed worker. action is the operation class to authorize, while sandbox_grants describes worker authority.
The permission engine checks policy; it does not restrict filesystem or network access by itself. If you add file or command tools, define the necessary grants and enforce the returned set through your worker or sandbox. Do not copy sandbox_grants => [] into a file-writing handler and assume it confines access.
Here the permission name is deliberately fixed and independent of the HTTP instance name. If you want each --name to have separate policy, pass $options{name} as the permission engine's name instead.
Why checks must precede side effects
When permission is missing, require_permission throws a special exception. Server catches it, asks, and may invoke the handler again. The assignment to $note therefore comes after the check.
With a local prompt, the server retries internally. Modern MCP form asking returns input_required; the client repeats the call with its answer. Earlier one-time grants survive permission retries within this invocation, but do not authorize the next call. Saved rules are rechecked.
Do not catch that exception as an ordinary failure around the permission check. It must reach Server's synchronous dispatch boundary. For several checks, complete all of them before modifying state or starting asynchronous work. An on_request hook also runs on retry, so it must not perform a once-only side effect before the handler's checks.
To choose client-side form asking for this example:
PERL_ANYEVENT_MCP_PERMISSION_ASK=auto perl echo-mcp --stdio
auto uses modern form elicitation when the client advertises support, otherwise the local helper. mcp requires that support; helper keeps the prompt local. The tiny try-echo client advertises no form support, so auto uses the helper there. To handle forms in a Perl client, see "on_request" in AnyEvent::MCP::Client and "elicitation" in AnyEvent::MCP::Permissions::Ask.
For grant definitions, subject scopes and multi-path operations, see AnyEvent::MCP::Server::Permissions and "Permission checks and retries" in AnyEvent::MCP::Server::Toolset.
Let an asynchronous operation finish later
A tool callback runs in the AnyEvent event loop. Blocking it with sleep or a synchronous long-running command also blocks other requests.
Add use AnyEvent; and register the following before mcp_start:
mcp_tool delayed_echo =>
"Return the supplied text after a delay of up to 60 seconds.",
{
type => "object",
properties => {
text => { type => "string", maxLength => 4096 },
seconds => {
type => "integer",
minimum => 0,
maximum => 60,
},
},
required => ["text", "seconds"],
},
sub {
my ($req, $args) = @_;
my $text = $args->{text};
defined $text and !ref $text and length $text <= 4096
or die "text must be a string of at most 4096 characters\n";
my $seconds = $args->{seconds};
defined $seconds and !ref $seconds
and $seconds =~ /\A[0-9]+\z/ and $seconds <= 60
or die "seconds must be an integer from 0 to 60\n";
$req->progress (0, 1, "Waiting");
my $timer = AnyEvent->timer (after => $seconds, cb => sub {
$req->{finished}
and return;
$req->progress (1, 1, "Done");
$req->reply ({
content => [{ type => "text", text => $text }],
});
});
$req->{on_cancel} = sub {
undef $timer;
};
};
The tool is advertised as delayed-echo, because registration converts underscores to hyphens. Ask the client to call it with text hello and seconds 2. The callback returns immediately; the timer supplies the reply later. Other requests can run while it waits.
Keep watcher objects alive while they are needed. Here the cancellation callback retains $timer, and the timer's callback retains $req and $text. Cancellation releases the timer. Replying finishes the request and removes its cancellation callback, releasing the watcher as well. No separate job registry is needed for this example.
Check finished in late completion callbacks before replying. Cancellation sets both finished and cancelled and sends no reply. For subprocesses or network work, the cancellation callback should stop that operation and release its resources instead of merely abandoning the eventual reply.
Server catches exceptions during synchronous dispatch, not exceptions from a later timer or I/O callback. If an asynchronous operation can fail, handle that failure in its completion callback and report it with error or reply, provided the request is still active.
progress only sends when the caller supplied a progress token. An outstanding tool request with a progress token emits an automatic elapsed-time heartbeat every 30 seconds. Delivery is best effort: stdio sends notifications directly, while Streamable HTTP sends them over the request's SSE response stream. Clients may ignore progress.
When to use the object interfaces
Simple owns one default Toolset and the blocking server lifetime. That is useful for a small standalone program. If you already run an event loop, want multiple transports or tool registries, or need custom protocol dispatch, construct the objects directly.
AnyEvent::MCP::Server::Toolset registers reusable tools. AnyEvent::MCP::Server handles the protocol. AnyEvent::MCP::Server::HTTP and AnyEvent::MCP::Server::JSONL manage connections. AnyEvent::MCP::Server::Request describes request fields, replies, progress and cancellation. The same tool callback model applies at both levels.
FUNCTIONS
- mcp_config %config
-
Adds server configuration. Repeated calls extend or replace previously declared values.
instructionsis treated as human-readable text and normalized.Server and transport options are passed to the underlying objects. Common options include:
- name => $instance
-
Local instance name used to select configuration and credentials. Independent of the name reported to MCP clients.
- server_name => $name
-
Advertised MCP server implementation name. Defaults to
AnyEvent::MCP. - server_version => $version
-
Advertised application version, not the MCP protocol revision. Accepts an ordinary Perl version number; Simple stringifies it for MCP. Defaults to the AnyEvent::MCP library version.
- server_info => { name => $name, version => $version }
-
Raw MCP server identity, passed through unchanged to the underlying server. Cannot be combined with
server_nameorserver_version. - instructions => $text
-
Human-readable guidance for the client, normalized when configured.
- short_instructions => $text
-
Optional condensed guidance for finding this server's tools. Used as the advertised MCP instructions when
auto_instructionsis enabled. - auto_instructions => $boolean
-
Enabled by default. Exposes full instructions through the generated
meta-instructionstool while advertising the short instructions if set. When short or custom instructions are provided, append a brief hint pointing to the full tool description; otherwise advertise full instructions as before. Disable to advertise full instructions and omit the generated tool. - custom_instructions => $text
-
Instance-specific purpose prepended to advertised instructions. Can also be set through
--custom-instructionsorcustom_instructionsin the program or instance section of the global INI configuration. - on_request => $callback->($server, $req)
-
Synchronous hook before each dispatch attempt. For example, refresh database state here. This does not replace dispatch or receive a completion callback, and permission retries can invoke it again.
- on_start => $callback->($server)
-
Called after the transport is ready, before entering the event loop. Use it for startup information or installing watchers. Stdout carries protocol messages in stdio mode; print diagnostics to stderr. The callback must not block.
- idle_exit => $seconds
-
Optional positive idle time for spawned stdio servers. With a multibroker advertising
anyevent-mcp/multibrokerversion 1, Simple requests shutdown once no MCP requests have been active for that long. The broker can ignore the request. An application may veto shutdown withon_idle_shutdown; Simple retries after the configured interval if it is declined. HTTP servers, ordinary clients and servers without this option are unaffected.
See AnyEvent::MCP::Server for further protocol options and events.
- mcp_permissions $object
-
Select the AnyEvent::MCP::Server::Permissions object used by the Simple starters. If never called (and no explicit
permissionsoption is supplied), Simple creates one automatically, named from the program and selected instance.mcp_permissions undefexplicitly disables the permission system: tool callbacks callingrequire_permissionthen fail instead of prompting. Applications can still passpermissionsthroughmcp_configor startup arguments when needed.The common
--askoption overrides the object's prompting mode, and CLI automatic permission rules precede configured rules and rules originally supplied with the object. Those rules are applied when starting the server, not whenmcp_permissionsis called. No permission object is created when it is explicitly disabled. - mcp_tool $name, $description, $input_schema, $callback->($req, $args)
-
Registers a tool named
$namewith$descriptionand the JSON Schema hash reference$input_schema.$descriptionis normalized likeinstructions.$callbackreceives an AnyEvent::MCP::Server::Request object$reqand its$req->{args}hash reference as$args, for convenience.Tools complete the request with
$req->reply ($result), or use$req->result ($data)and$req->error ($message)for convenience. Request context is available directly in the hash, for example$req->{tool}and$req->{server}. - $server_options = mcp_getoptions ({ %settings }, @getopt_options)
-
Parse the switches documented in "COMMON COMMAND-LINE OPTIONS" alongside application-specific Getopt::Long option specifications:
my $verbose; my $options = mcp_getoptions ( { usage => "Usage: $0 [OPTION]... WORKDIR\n", description => "Provide example tools through MCP.", option_heading => "Example options:", options => [ ["--verbose", "Show additional diagnostics"], ], examples => " $0 --stdio ./project", path => "/", }, "verbose!" => \$verbose, ); @ARGV == 1 or die "workdir required\n"; mcp_start %$options;The optional leading hash accepts these help settings:
- usage => $text
-
Usage synopsis, including its trailing newline. A default synopsis is generated when omitted.
- description => $text
-
Introductory help paragraph.
- options => [[$label, $description]...]
-
Application option labels and descriptions. A plain string among the pairs starts a new section; a string at the beginning replaces the default section heading.
- option_heading => $text
-
Initial section heading, defaulting to
Application options:. - examples => $text
-
Preformatted examples.
- without => [OPTION...]
-
Exclude selected common options by their long names, for example
without => ["ask"]. The parser rejects excluded switches, and--helpomits them. All common options are enabled by default. - print_url_extra => $callback
-
Append application-specific URLs to
--print-urloutput. Called once with the resolved HTTP settings after the normal MCP URLs have been printed. - default_port => $port
-
Choose an application-specific fallback port for
--print-url, without replacing the bind address or overriding ports explicitly specified by--bindor configuration. The application must also pass it tohttp_settingswhen starting its listener.
See "COMMON COMMAND-LINE OPTIONS" for the full reference to shared server switches. Application-specific Getopt::Long options are parsed alongside them.
These switches also appear in
--help; application options are passed through to Getopt::Long. Other leading hash settings (e.g.path,auth,url_scheme) go tomcp_start. Parse positional@ARGVin the application;mcp_getoptionsdeliberately does not require them for help or URL discovery. Default activity logging includes asynchronous tool failures and formats time, program, instance and PID. EnvironmentPERL_ANYEVENT_LOGcan select destinations and verbosity. - mcp_tool_help ($enabled, @toolsets)
-
If
$enabledis true, print the definitions registered in the supplied AnyEvent::MCP::Server::Toolset objects and exit. Otherwise do nothing. Call after registering tools but before starting listeners for executables which manage their own toolsets. Only registered tools appear. - mcp_log $message
-
Emit operator-facing activity to the configured AnyEvent::Log destination, bypassing its diagnostic verbosity filter.
--quietsuppresses this log. - mcp_log_request ($server, $req, %extra)
-
on_requestcallback to report tool invocations once across permission retries, and log tool-error replies, including asynchronous ones. It logs selected arguments rather than entire request or reply payloads. This includes JSON-quoted previews of command arguments and VCS filenames (up to four, 80 characters each), and Vimexcommands (up to 200 characters). These can contain sensitive text. The Simple starters install it by default; custom servers can use it too.%extraappends application-specifickey=valuefields in key order. Sanitize sensitive arguments before passing them. - mcp_start %config
-
Starts and runs the usual server. When
stdiois true orPERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOLisstdio, usesmcp_stdio. Otherwise starts HTTP without printing its URL. HTTP-capable executables provide--print-urlto retrieve the URL explicitly.The HTTP defaults are IPv4 loopback, a stable name-derived port in 16384..32767, and
/as the endpoint path. Without explicittokens, one server-specific token is derived from the private global secret. The selected token authenticates either its URL path or anAuthorization: Bearer TOKENheader at the clean URL returned by$server->url (0). The corresponding executable's--print-urloption prints the first accepted token in its URL.nameselects the[instance NAME]configuration section and credential. It defaults todefault. Named settingsbind,path,url_host,url_scheme,tokens,tls_certandtls_keyare loaded from the global configuration. Explicittokens(an ordered, nonempty array reference of URL-safe strings) replaces the configured list and the derived default. Every token works in the URL and bearer header. An explicitbindoverrides the configured bind address. Other arguments override these settings.The global secret is generated automatically when needed; see "GLOBAL CONFIGURATION" in AnyEvent::MCP. No configuration is loaded for stdio. Unless explicitly disabled using
mcp_permissions undef, Simple constructs a default permission engine.--askand automatic permission rules configure it along with any application-supplied permission object. HTTP startup neither prints to stdout nor changes its buffering.mcp_startdoes not parse@ARGV; applications parse their own options. The bundled executables usemcp_getoptions, which handles shared options and URL discovery before starting the event loop. - mcp_connect %config
-
Run a reverse-connecting JSONL server using
connect => "http[s]://host:port/token/alias". HTTPS verifies the server certificate and hostname. It sends the authenticated extension hello only after the transport is established, then serves MCP over the socket. Refused TCP connections retry every second for at most sixty attempts, and unexpected established disconnects start a new retry period. Other TCP setup and TLS handshake errors are reported and stop the server. Calls are cancelled rather than replayed. This connection has no spawned-child lifecycle authority. - mcp_stdio %config
-
Creates and runs a server over stdin/stdout. Arguments override the collected configuration. Stdout buffering is disabled. On stdin EOF, pending replies finish and stdout drains before this function returns. Stream errors close the connection and cancel pending requests.
- mcp_http %config
-
Creates and runs an HTTP server. For example:
mcp_http host => "127.0.0.1", port => 31740, path => "/mcp/", tokens => ["your-long-random-secret"];Arguments override the collected configuration. Unlike
mcp_start, this function does not derive or supply authentication. Always passtokens, or explicitly passauth => "none"when a trusted embedding layer enforces access. Omitting both is an error, not an unauthenticated default. It does not print a URL; useon_startfor application-specific startup output. Neither function implements OAuth or Basic authentication. See "AUTHENTICATION" in AnyEvent::MCP::Server::HTTP for details.All three starters return when the server is closed or on
SIGINTorSIGTERM. Signal shutdown closes connections and cancels outstanding requests. The signal watchers belong to the blocking call.
COMMON COMMAND-LINE OPTIONS
mcp_getoptions parses these options for executables using AnyEvent::MCP::Server::Simple. The executable's own OPTIONS section documents any additional switches or differences in shared-option behavior. An application can exclude specific common switches via without.
- --name NAME
-
Select the instance (default
default). NAME starts with an ASCII letter, digit or underscore; subsequent characters may also contain.,@,+and-. Selects[instance NAME]configuration, derived HTTP port and credentials; does not change the advertised MCP implementation name. Example:--name project. - --bind ADDRESS[:PORT]
-
Override HTTP listening address and port. Defaults to
127.0.0.1and a stable instance-derived port in 16384..32767.:31740uses the loopback address and port 31740;127.0.0.1:31740specifies both. Port zero requests an ephemeral port and is incompatible with--print-url. Ignored for stdio-only startup. - --tls-cert FILE
-
Enable opportunistic HTTPS using a PEM certificate chain. Without
--tls-key, FILE must also contain the private key. The same listener continues to accept plain HTTP. - --tls-key FILE
-
Private-key PEM file for
--tls-cert. If supplied alone, FILE must contain both certificate chain and private key. RequiresNet::SSLeay. - --token TOKEN
-
Accept TOKEN for HTTP authentication. Repeat to accept multiple tokens. Explicit tokens replace configured or master-secret-derived defaults. Tokens work both as credential-bearing URL components and with the
Authorization: Bearer TOKENheader. Example:--token first --token second. - -s, --set KEY=VALUE
-
Override one trusted configuration entry for the selected instance in this process. Applied after
[program NAME]and[instance NAME]defaults, without changing the configuration file. Repeat to override multiple entries; the last assignment to a key wins. Empty values suppress inherited settings, and additional equals signs belong to the value. The supported keys depend on the server (for example,executable.perlandprepend-pathin mcp-fs). Example:-s executable.perl=/opt/perl/bin/perl. - --stdio
-
Serve MCP JSONL on stdin/stdout rather than the default HTTP listener. Applications with auxiliary listeners can keep those active. Cannot combine explicitly with
--connect. - --connect URL
-
Reverse-connect to an upstream multibroker. For example:
http://host:port/TOKEN/aliasorhttps://host:port/TOKEN/alias. HTTPS requires successful certificate and hostname verification; it never falls back to plaintext. Replaces the default MCP listener and overrides implicit stdio selection. Cannot combine with explicit--stdio. - --custom-instructions TEXT
-
Override configured instance-purpose guidance describing when MCP clients should use the server. Example:
--custom-instructions 'Use for build logs'. - --auto-allow TOOL[,ACTION[,CAPABILITY]]
-
Add a process-local permission allow rule, repeatable. TOOL identifies the permission-checked tool; ACTION and CAPABILITY narrow the match. Missing fields and
*match anything. Example:--auto-allow '*,read,workdir-read'. Rules run in command-line order before saved rules; they cannot grant permissions to tools that do not check permissions. See "auto_rules" in AnyEvent::MCP::Server::Permissions. - --auto-deny TOOL[,ACTION[,CAPABILITY]]
-
Add a repeatable process-local deny rule with the same matching syntax and evaluation order as
--auto-allow. Example:--auto-deny '*,exec'. - --ask MODE
-
Choose how permissions or other human input are requested:
helper,tty,yad,mcp, orauto.noneimmediately declines requests that would otherwise require prompting; existing allow and deny rules still apply. Multibroker replies to downstream forms with a standard decline. The default depends on the application and its multibroker environment. - --quiet
-
Suppress routine tool activity and tool-failure logging. Warnings and ordinary diagnostics remain;
PERL_ANYEVENT_LOGdetermines diagnostic levels and destinations. - --print-url[=USER]
-
Print credential-bearing URLs and exit without starting a listener. With managed users, prints each effective enabled user's URL, or only the exact username USER. Comments identify scope-qualified principals and the selected auxiliary connection user. With configured TLS, HTTPS is printed before HTTP. Explicit tokens retain a single-token output and cannot be combined with a user selector. Requires a predictable, nonzero port and a persistent master secret for derived credentials. Example:
--name project --print-url=claude. - --print-urls
-
Alias for
--print-url. - --tool-help
-
Print currently registered tool names, descriptions, argument types, required fields and defaults; exit without starting the MCP listener. Registered tools can depend on installed utilities and application setup.
- --help
-
Print shared and application-specific command-line help; exit without starting a server. Invalid options instead report usage.