CLI integrations

CLI integrations let an AI client run explicitly approved operations of programs installed on the MCPBox host. They are managed separately from MCP servers and Market packages.

Add a program

1. Install the program on the MCPBox host.
2. Open the global CLI page. Run Check and add found binaries, or create an entry manually.
3. Set a stable lowercase ID (slug), executable, description and allowed operations.
4. Review the limits and enable the entry.
5. Open a project's CLI view and connect it to that project.

Discovery checks the server OS and PATH without installing or executing binaries. Startup discovery adds only absent available entries; it preserves existing configuration and project links. Deleted catalog IDs are remembered so they are not automatically restored.

The default starter catalog is https://mcpbox.sh/cli.json, with a bundled fallback if loading fails. Existing definitions change only through the explicit review/apply flow. Finding docker in PATH, for example, does not establish that its daemon works.

Define allowed operations

Each operation is an exact command such as status or mcp list. Extra arguments are denied unless an entire ordered argument vector is approved.

Example operation configuration:

[
  { "command": "status" },
  { "command": "diff" },
  { "command": "log", "argument_sets": [["-n", "5"], ["--oneline", "-n", "10"]] }
]

In the UI, the optional argument-set JSON maps operation names to lists, for example {"log":[["-n","5"]]}. Empty extra arguments are allowed for registered operations. This is not a prefix or wildcard allowlist. Operation words are split on whitespace; use argument sets for a literal argument containing spaces.

Use through MCP

Projects with active CLI links expose three tools:

Tool	Purpose
cli_list	List available project CLI IDs and descriptions.
cli_describe	Inspect approved operations, argument sets and limits.
cli_execute	Execute an approved operation.

A project can expose CLI tools without an MCP server. Permissions are checked again for each execution; disabling or unlinking blocks subsequent calls. An already running process is not stopped by a registry edit.

Execution limits

Commands run directly without a shell. Configure working folders in the project CLI tab: a list of existing absolute host paths including subfolders, or explicit All folders access. These settings apply to all CLI integrations in this project. Requests may choose an allowed working folder; environment overrides are not accepted. Relative executable paths and common shell binaries are rejected; use a binary name resolved through the host's PATH or an absolute executable path. Interactive input is unsupported.

Defaults are 30 seconds and 1 MiB combined output. Configurable limits are 1–300 seconds and 1 KiB–4 MiB. Results include stdout, stderr, exit code, timeout and truncation flags. CLI writes and administrative execution require pro:admin.

This is an administrator-managed allowlist, not an OS sandbox. Approved programs may modify files, access networks or execute their own scripts. Audit records omit arguments and output. On Windows, timeout cancellation currently targets the direct child rather than its complete process tree.

SSH operations

Only ssh/ssh.exe additionally receives the service account's HOME and SSH_AUTH_SOCK, when available; other CLI programs retain the restricted environment. Configure SSH keys, known_hosts and BatchMode yes for the account running MCPBox. Host key checking remains enabled. Use a trusted absolute executable path if PATH can be modified.

For binary ssh, register a host alias such as operation mcpbox-linux with exact argument sets like [["hostname"], ["docker ps"]]. The call {"cli":"ssh-linux","command":"mcpbox-linux","args":["docker ps"]} uses that registered CLI ID and operation. SSH passes the remote command to the remote shell: approve only exact trusted strings. No wildcard permission is added.

For Git, Go, Composer and other workspace operations, add persistent folders in the project CLI tab. The temporary working directory is not a filesystem sandbox; files needed by later invocations must be saved in an explicitly configured persistent location.

Choose a working folder

Folder settings belong to the project and apply to all its CLI integrations. Listed folders include subfolders; All folders permits any existing folder accessible to the MCPBox account. This controls the working directory, not filesystem isolation. FilesSystemMCP permissions and MCP server working folders are separate.

Read directory_policy with cli_describe, then pass an absolute working_directory to cli_execute, for example {"cli":"git","command":"fetch","working_directory":"/srv/repos/app"}. The operation and its arguments must still be approved. Relative, missing and disallowed folders are rejected; symlinks are resolved before checking containment.

With a saved restricted list, omitting the folder uses its first entry, or a temporary folder if empty. With All folders, omission uses root_path, or a temporary folder if empty. Existing projects keep their previous default until a folder policy is saved. Temporary folders are removed after execution. Saving folder permissions requires pro:admin.