Plugin: mcp: Model Context Protocol server🔗
Warning
This plugin is experimental. The interface, options, and behavior may change in future releases without notice.
The mcp plugin starts a Model Context Protocol (MCP) server that exposes ascli to AI assistants and LLM-based tools.
The server registers a single tool, execute_ascli_command, which executes any ascli command in-process and returns the result as text.
Info
The mcp and rack gems are required, see section Installing Optional Gems.
Install them with the following command:
gem install mcp rack
Usage🔗
ascli mcp server
ascli mcp server @: instructions="Use this server to manage Aspera transfers"
ascli mcp server @: transport=http
server command options🔗
The server command accepts an optional Hash argument with the following keys.
Keys of a transport are refused with the other transport.
General🔗
| Key | Type | Default | Description |
|---|---|---|---|
transport |
string |
stdio |
Transport to use: stdio or http |
description |
string |
- | Short description of the server shown in the AI client UI |
instructions |
string |
- | Longer hint shown to the AI client describing what the server does and how to use it |
protocol_version |
string |
- | MCP protocol version to advertise, for example, 2024-11-05 |
validate_tool_call_arguments |
boolean |
true |
Whether to validate tool arguments against the input schema |
max_text_bytes |
integer |
100000 |
Maximum byte size of the JSON text content for list results. Items are appended whole until the limit is reached; the full list is always available in structuredContent |
stdio transport🔗
| Key | Type | Default | Description |
|---|---|---|---|
max_line_bytes |
integer |
4194304 (4 MiB) | Maximum JSON frame size in bytes |
Note
stdio transport and server description - The MCP protocol does not carry a description field in the initialize handshake.
For stdio servers, AI clients (Claude Desktop, VS Code, Bob, and so on) cannot retrieve the description automatically.
Add a "description" field directly in the client's mcpServers configuration to display it in the UI.
http transport (Streamable HTTP)🔗
| Key | Type | Default | Description |
|---|---|---|---|
url |
string |
http://127.0.0.1:3000 |
Address and port the server listens on, without path, for example, http://0.0.0.0:3000. Use https:// for TLS. |
cert |
string |
- | With https://: path to the TLS certificate file, PEM or PKCS12 (.p12, .pfx). Without cert and key, a self-signed certificate is generated. |
key |
string |
- | With https://: path to the PEM private key file, or the PKCS12 passphrase. |
chain |
string |
- | With https://: path to the PEM certificate chain file. |
public_url |
string |
from url |
URL of the server for clients, used in OAuth metadata and in the URL of secret pages, for example, https://your-server:3000. Mandatory with oauth when the host of url is 0.0.0.0 or ::. |
auth_token |
string |
- | Static Bearer token. If set, all MCP requests must carry Authorization: Bearer <token>, else HTTP 401. Cannot be empty. It is also the access code asked on secret pages, and on the consent page with oauth. Generate it with openssl rand -hex 32. |
auth_token_min_bits |
integer |
80 |
Minimum estimated strength of auth_token, in bits: a weak token is refused at startup. The estimate uses the optional gem zxcvbn if installed, else a built-in estimate. 0 disables the check. |
oauth |
boolean |
false |
Enable OAuth 2.0 PKCE flow with dynamic client registration. When true, clients register automatically and users authenticate via a browser consent page. |
oauth_access_token_ttl |
integer |
3600 |
OAuth access token lifetime in seconds. |
oauth_refresh_token_ttl |
integer |
2592000 |
OAuth refresh token lifetime in seconds (30 days). |
stateless |
boolean |
false |
Enable stateless mode |
allowed_origins |
Array<string> |
- | List of allowed origins |
allowed_hosts |
Array<string> |
- | List of allowed hostnames |
session_idle_timeout |
integer |
- | Idle session timeout in seconds |
max_sessions |
integer |
- | Maximum number of concurrent sessions |
Note
port and bind are deprecated: use url, for example, url=http://0.0.0.0:8080 instead of port=8080 bind=0.0.0.0.
For the addresses the server listens on, and HTTPS, see Web service.
Security🔗
Warning
The tool executes any ascli command with the credentials and presets of the user running the server.
When the host of url or public_url is not a loopback address, auth_token is mandatory, also with oauth: the server refuses to start without it.
With the http transport:
- With
oauth, the consent page asks forauth_tokenas access code, else anyone reaching the server could approve its own client. It shows where the authorization is sent (origin ofredirect_uri): allow only if it is the expected AI client, for examplehttp://127.0.0.1:<port>. - For local-only deployments (hosts of
urlandpublic_urlare loopback, see Web service),auth_tokenandoauthare optional but recommended: on a host shared with other users, they can also reach the server. Withoutauth_token, the consent page only asks to click Allow. auth_tokenandoauthcan coexist: a request is accepted if it carries a valid static token or a valid OAuth access token.- A weak
auth_tokenis refused at startup (seeauth_token_min_bits): generate it withopenssl rand -hex 32. - On a network, use
https://inurl(or a reverse proxy with TLS): withhttp://, the token is sent in clear. allowed_hostsandallowed_originsprotect against DNS rebinding but do not authenticate clients. They apply to all endpoints, also OAuth and secret pages, which also accept the origin ofpublic_url(for a reverse proxy that changes headerHost).
With both transports:
- Extended value
@stdin:is refused. @secret:is entered by the user on a web page, see Secrets entered in a web page.- Secrets are hidden in responses, also a value shorter than 8 characters as a word in a text (for example, a short password in an error message).
- The Security Level is
highby default:@ruby:,@file:(also in the parameters of stores of optionvault),@uri:, and@env:are refused, and a secret must be the whole value: hidden in results, it cannot be processed by another extended value. It applies to commands sent by the client, and to presets, because the client can modify presets. Commands sent by the client cannot change optionsecurity. Features that execute code, such as optionnotify_templateor commandconfig plugins create, plugins, and writing to a file chosen by the client (optionout.file), are refused, see Security Level. Files can be written (for example byconfig download, or by a transfer that receives files) only inwritable_paths, none by default: without it, the client cannot download files. It applies to files written on the system that runs the server: not to a transfer with agentnode(--transfer=node), which writes on the node.
To use another level, set option security when starting the server, for example:
ascli mcp server --security.level=medium --security.allowed_paths.0=$HOME/.aspera/ascli/my_private_key
To let the client download files in a folder, keep the level high and give the folder:
ascli mcp server --security.writable_paths.0=$HOME/Downloads/ascli
Note
A level set by option also applies to the parameters of the server command: for example, auth_token=@env:MCP_TOKEN requires level low.
Without option security, the parameters of the server command are not restricted.
A preset created by aoc wizard or faspex5 wizard reads the private key with @file:.
With level high, either store the key in the preset (ascli config preset set <AOC_ORG> private_key @file:<PATH>, without @val:), or use level medium with the key in allowed_paths.
In the same way, a secret of a vault read from a file (for example, token of HashiCorp Vault: @file:<path>) requires level medium with the file in allowed_paths.
HTTP endpoints🔗
With the http transport, the server exposes the following endpoints:
| Endpoint | Description |
|---|---|
GET / |
Discovery: JSON object with name, version, and description of the server, no authentication |
POST, GET, DELETE /mcp |
MCP endpoint (Streamable HTTP), the URL to configure in the AI client. Requires auth_token or an OAuth access token, if configured |
GET, POST /secret/<id> |
Secret pages, see Secrets entered in a web page |
GET /.well-known/oauth-authorization-server |
With oauth: OAuth discovery metadata (RFC 8414) |
POST /oauth/register |
With oauth: Dynamic client registration (RFC 7591) — any client may register and receive a client_id. At most 100 clients are kept: beyond, the least recently used is removed. At most 10 redirect_uris, absolute and without fragment |
GET /oauth/authorize |
With oauth: Consent page shown to the user in a browser, with the client_id and where the code is sent (origin of redirect_uri) |
POST /oauth/authorize |
With oauth: Processes the user decision (allow/deny) and issues an authorization code |
POST /oauth/token |
With oauth: Exchanges the code for tokens (authorization_code) or renews them (refresh_token) |
AI clients that support the discovery endpoint (such as Bob) read the description from it and display it in their MCP server list without any manual configuration.
AI clients that support the MCP Authorization spec (such as Bob) detect the OAuth endpoints automatically via the WWW-Authenticate header returned on HTTP 401, register dynamically, and launch the browser-based login flow without any extra configuration.
Secrets entered in a web page🔗
Extended Value @secret:[name] asks for a secret, for example, a password.
In MCP server mode, there is no terminal: the user enters the secret on a web page of the server instead, following the URL mode elicitation of the MCP protocol.
The secret goes from the browser to the MCP server only: it is not sent to the MCP client or the AI model, and it is hidden in the results of the command.
@secret: can be used in commands sent by the AI client, for example, --password=@secret:password, and in presets of the user running the server.
For a command that needs a secret:
- The server replies to the tool call with the URL of a secret page.
- The MCP client shows the URL and asks the user for consent to open it in a browser.
- The user enters the secret on the page and submits it, or cancels.
- The MCP client calls the tool again, and the server executes the command with the secret.
If the command needs several secrets, these steps are repeated for each secret.
The secret page is served:
- With the
httptransport: by the MCP server, at<public_url>/secret/<id>. Ifauth_tokenis set, the page also asks for it as access code. Setpublic_urlif the browser does not reach the server on the address ofurl. - With the
stdiotransport: by a local web server onhttp://127.0.0.1with a random port, started on first use.
A secret request expires after 10 minutes. Secrets are kept in memory only, until the command completes.
Note
The MCP client must support URL mode elicitation (capability elicitation.url), else the command fails with an error.
Protocol 2026-07-28 (result input_required) and 2025-11-25 (request elicitation/create from the server) are supported.
With protocol 2025-11-25, the http transport must not be stateless.
Examples🔗
Start an MCP server over stdio (default - suitable for use as an MCP server in an IDE or AI tool):
ascli mcp server
Start an MCP server over HTTP on port 8080:
ascli mcp server @: transport=http url=http://0.0.0.0:8080 auth_token=@env:MCP_TOKEN
Start an MCP server over HTTPS, with a certificate:
ascli mcp server @: transport=http url=https://0.0.0.0:8443 cert=<PATH>/cert.pem key=<PATH>/key.pem auth_token=@env:MCP_TOKEN
Start with custom instructions and a specific protocol version:
ascli mcp server @: instructions="Aspera transfer automation" protocol_version=2024-11-05
Start an MCP server with OAuth 2.0 PKCE authentication (for AI clients such as Bob that support the MCP Authorization spec):
ascli mcp server @: transport=http url=http://0.0.0.0:3000 public_url=http://your-server:3000 oauth=true auth_token=@env:MCP_TOKEN
MCP client configuration🔗
Streamable HTTP transport🔗
Local server (no authentication required)🔗
Start the server in a separate terminal first:
ascli mcp server @: transport=http
Then register it in the AI client's MCP configuration file.
For IBM Bob, add to .bob/mcp.json in your project (or ~/.bob/mcp.json for global configuration):
{
"mcpServers": {
"ascli": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp"
}
}
}
For other clients (Claude Desktop, VS Code, and so on):
{
"mcpServers": {
"ascli": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
Remote server with static token🔗
When the server is exposed on a non-local address, auth_token is required.
Option A: static Bearer token - suitable for all MCP clients. Set the token in the environment and start the server:
export MCP_TOKEN=$(openssl rand -hex 32)
ascli mcp server @: transport=http url=http://0.0.0.0:3000 auth_token=@env:MCP_TOKEN
For IBM Bob, pass the same token in the Authorization header:
{
"mcpServers": {
"ascli": {
"type": "streamable-http",
"url": "http://your-server:3000/mcp",
"headers": {
"Authorization": "Bearer <TOKEN>"
}
}
}
}
For other clients (Claude Desktop, VS Code, and so on):
{
"mcpServers": {
"ascli": {
"type": "http",
"url": "http://your-server:3000/mcp",
"headers": {
"Authorization": "Bearer <TOKEN>"
}
}
}
}
Remote server with OAuth 2.0 PKCE🔗
Option B: OAuth 2.0 PKCE flow - for AI clients that support the MCP Authorization spec (such as Bob).
No token to configure in the client: the client registers dynamically and opens a browser window for user consent on first connection.
The consent page asks for the access code: the value of auth_token.
Start the server with OAuth enabled:
ascli mcp server @: transport=http url=http://0.0.0.0:3000 public_url=http://your-server:3000 oauth=true auth_token=@env:MCP_TOKEN
For IBM Bob, register the URL with no extra configuration:
{
"mcpServers": {
"ascli": {
"type": "streamable-http",
"url": "http://your-server:3000/mcp"
}
}
}
Bob detects the OAuth endpoints via the WWW-Authenticate header on the first HTTP 401 response and triggers the browser-based login flow automatically.
Note
With http transport, the client connects to a running server process.
The server must be started and kept running independently before the AI client tries to connect.
stdio transport🔗
The client launches ascli directly as a subprocess.
Add the following to the AI client's MCP configuration file.
IBM Bob stdio🔗
For IBM Bob, add to .bob/mcp.json in your project (or ~/.bob/mcp.json for global configuration):
{
"mcpServers": {
"ascli": {
"type": "stdio",
"command": "/path/to/bin/ascli",
"args": ["mcp", "server"],
"description": "Aspera CLI MCP server"
}
}
}
For other clients (Claude Desktop, VS Code, and so on), the configuration is identical.
Claude Desktop stdio🔗
Find the configuration file as specified in Claude Desktop Documentation.
Place this section in mcpServers:
{
"mcpServers": {
"ascli": {
"command": "ascli",
"args": ["mcp", "server"]
}
},
...
}
Development mode for stdio🔗
If the ascli gem is not installed and you are running directly from the source tree, Ruby will not find the lib/ directory automatically.
Add the RUBYLIB environment variable pointing to the lib/ directory of the project:
{
"mcpServers": {
"ascli": {
"type": "stdio",
"command": "/path/to/aspera-cli/bin/ascli",
"args": ["mcp", "server"],
"env": {
"RUBYLIB": "/path/to/aspera-cli/lib"
}
}
}
}
Tested commands for mcp🔗
Note
Add ascli mcp in front of the following commands:
server
server @: transport=http port=13777
End-to-end AI testing🔗
The file docs/test-mcp-with-ai.md contains a step-by-step test procedure for validating the MCP server with a live AI assistant (Bob, Claude Desktop, VS Code Copilot, or any MCP-capable client).
It covers tool visibility, self-discovery, Hash schema introspection, option listing, documentation retrieval, live transfer tasks, truncation handling, error handling, and credential safety.
MCP usage patterns for AI🔗
Tip
This section is for AI assistants using the MCP server. Follow these patterns to avoid common first-call failures and unnecessary retries.
Session bootstrap🔗
Always start a session with two discovery calls before doing anything else:
["config", "preset", "list"]
["config", "preset", "show", "default"]
The second call returns the mapping from plugin to preset_name so you know which credentials are active for each plugin.
Command discovery🔗
Always use ["config", "commands", "<plugin>"] to enumerate the commands of a plugin and their syntax.
Add command words to list only the commands under that path, e.g. ["config", "commands", "aoc", "files"].
A line ending with <command...> provides the commands of another plugin, given by (see: ...).
Use option --expand-mounts=yes to list them in place.
Omit <plugin> to list the commands of all plugins (much larger result).
Never guess command names from training data: names like shared_folders vs shared_inboxes are easily confused.
Schema introspection for Hash arguments🔗
Whenever a command syntax shows a Hash argument (e.g. <account:Hash>), call help in its place before the real call:
["<plugin>", "<cmd>", ..., "help"]
This returns a table of field names, types, and descriptions. Never infer field names from server error messages.
Secrets🔗
To use a secret the user did not provide (password, passphrase), pass @secret:<name> as value.
The user enters it on a web page and you never see it: prefer it to asking for the secret in the conversation.
["server", "browse", "/", "--url=ssh://host:33001", "--username=user", "--password=@secret:password"]
Async transfers and cross-call status tracking🔗
The direct agent keeps transfer state in-memory.
A job started in one MCP call cannot be monitored in a subsequent call: the in-memory agent is gone between calls.
Use the transferd agent when you need to check transfer status in a later call:
["server", "upload", "--transfer=transferd", "--to-folder=/dst", "/local/file"]
The desktop agent is also unaffected because it runs in an external process.
Workspace context for AoC🔗
aoc files and aoc packages commands require a workspace context.
If no default workspace is configured in the preset, always add --workspace=NAME:
["aoc", "files", "ls", "/", "--workspace=MyWorkspace"]
List available workspaces with ["aoc", "user", "workspaces", "list"].
Admin operations and privilege checks🔗
Before calling any admin sub-command, verify that the active preset has admin rights.
access_denied typically means the wrong preset is active, not a syntax error.
Check with:
["config", "preset", "show", "<preset_name>"]