How do I use Cuba-Exec?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cuba-Exec start a background npm dev server" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Cuba-Exec

by LeandroPG19

Overview Schema Source Related Servers Discussions Admin

Python

Local

🚀 Cuba-Exec

Advanced shell command execution for AI agents — A Model Context Protocol (MCP) server with security policy engine, process lifecycle management, bounded output capture, POSIX signals, and token-efficient responses.

6 tools. Zero configuration. POSIX-native. Security by default.

Why Cuba-Exec?

Existing command execution MCPs are thin wrappers over subprocess.run. Cuba-Exec solves the real problems:

Problem	Existing MCPs	Cuba-Exec
Output overflow (cat /dev/urandom)	❌ OOM crash	✅ 64KB bounded
Background processes	❌ Sync only	✅ Start/status/signal
Kill child processes (npm run dev)	❌ Orphaned children	✅ Process group kill (setsid)
Send stdin (REPLs, prompts)	❌ Not supported	✅ Full stdin pipe
POSIX signals (SIGTERM, SIGKILL)	❌ Not supported	✅ 5 signals + graceful shutdown
Command allowlist/blocklist	⚠️ Some	✅ Both + shell operator validation
Directory restriction	⚠️ Rare	✅ Path-resolved anti-traversal
Audit logging	❌ None	✅ Structured JSON to stderr
Token-efficient output	❌ Verbose JSON	✅ TOON compact format
Idle process cleanup	❌ Resource leak	✅ 1-hour TTL auto-cleanup
Fork bomb protection	❌ None	✅ Semaphore(20)
Process discovery	❌ None	✅ List all managed processes

Related MCP server: Shell MCP Server

Quick Start

1. Prerequisites

Python 3.14+
Linux/macOS (POSIX required for process groups)

2. Install

git clone https://github.com/LeandroPG19/cuba-exec.git
cd cuba-exec
uv venv && uv pip install -e .

3. Configure your AI editor

{
  "mcpServers": {
    "cuba-exec": {
      "command": "/path/to/cuba-exec/.venv/bin/python",
      "args": ["-m", "cuba_exec"]
    }
  }
}

Zero environment variables needed. Zero configuration files. It just works — with 25 dangerous commands blocked by default.

The 6 Tools

`run` — Execute and wait

run(command="ls -la", cwd="/tmp", timeout_ms=5000)

Parameter	Type	Default	Description
`command`	string	required	Shell command
`cwd`	string	None	Working directory
`env`	dict	None	Environment variables (merged with current)
`timeout_ms`	int	30000	Timeout in milliseconds
`max_output`	int	65536	Output buffer size (bytes)
`shell`	string	/bin/sh	Shell executable

Response:

[exit:0 time:12ms trunc:no]
total 156
drwxrwxrwt 22 root root 4096 Mar  8 2026 .
...

`start` — Background process

start(command="npm run dev", cwd="/app")

Response:

[pid:12345 state:running]
Background process started. Use status(12345) to check output.

`status` — Check background process

status(pid=12345, tail_bytes=4096)

Response:

[pid:12345 state:running exit:- time:5432ms bytes:8192 trunc:no]
Server running on http://localhost:3000

`send_signal` — POSIX signals

send_signal(pid=12345, sig="SIGTERM")

SIGTERM triggers graceful shutdown: SIGTERM → wait 5s → SIGKILL.

Valid signals: SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT.

`send_input` — stdin pipe

send_input(pid=12345, stdin="print('hello')\n")

For interactive processes (Python REPL, bash prompt, etc.).

`list_processes` — Process discovery

list_processes()

Response:

[processes:2]
  pid:12345 state:running exit:- time:5432ms bytes:8192 cmd:npm run dev
  pid:12346 state:completed exit:0 time:1200ms bytes:256 cmd:echo done

🛡️ Security Policy Engine

Cuba-Exec includes a multi-layer security engine — the most comprehensive of any MCP command server.

Security Layers

Layer	Description	Config
Command Allowlist	Only listed commands can execute	`CUBA_EXEC_ALLOWED_COMMANDS`
Command Blocklist	Dangerous commands always rejected	`CUBA_EXEC_BLOCKED_COMMANDS`
Shell Operator Validation	Validates each sub-command after `;`, `&&`, `\|\|`, `\|`	Automatic
Directory Restriction	Restrict `cwd` to allowed paths (anti-traversal)	`CUBA_EXEC_ALLOWED_DIRS`
Audit Logging	Structured JSON log of every execution	`CUBA_EXEC_AUDIT`

Default Behavior (Zero Config)

Out of the box, Cuba-Exec blocks 25 dangerous commands:

rm, dd, mkfs, shutdown, reboot, halt, poweroff, init, systemctl,
passwd, chown, chmod, chgrp, mount, umount, fdisk, parted,
iptables, nft, ip6tables, crontab, at, useradd, userdel,
groupadd, groupdel, visudo

Production Hardening

export CUBA_EXEC_ALLOWED_COMMANDS="ls,cat,echo,grep,find,head,tail,wc,git,python3,node,npm"
export CUBA_EXEC_BLOCKED_COMMANDS="rm,dd,mkfs,shutdown"
export CUBA_EXEC_ALLOWED_DIRS="/home/user/project,/tmp"
export CUBA_EXEC_AUDIT=1

Shell Operator Bypass Prevention

ls && rm -rf / — the rm after && is validated against blocklist/allowlist too.

Operators parsed: ;, &&, ||, | — each sub-command checked independently.

Audit Log (stderr)

{"ts":"2026-03-08T15:00:00-0600","event":"exec","command":"ls -la","pid":12345,"exit":0,"ms":12,"ok":true}

Output Format (TOON)

All responses use Token-Oriented Object Notation — compact headers that save ~200 tokens per tool call vs verbose JSON.

[exit:0 time:1543ms trunc:no]
...output...

Error Codes

Error	Exit Code	Field	Example
Command not found	127	`ENOENT`	`nonexistent_binary`
Permission denied	126	`EACCES`	`cat /etc/shadow`
Timeout	-1	`TIMEOUT`	`sleep 60` with 1s timeout
Signal killed	-9	`SIGKILL`	Process killed by signal
Blocked by policy	—	`BLOCKED`	`rm -rf /`

Head+Tail Output Buffer — Shannon (1948)

Command output has high entropy at the extremes (preamble + results/errors) and low entropy in the middle (progress bars, repetitive logs).

┌─────────────┬───────────────────────────────┬──────────────────────────────────────────┐
│  Head (25%) │        Truncated middle       │                Tail (75%)                │
│  ~16KB      │   [... N bytes truncated ...] │                ~48KB (ring buffer)       │
└─────────────┴───────────────────────────────┴──────────────────────────────────────────┘

Head: First 25% of buffer — captures headers, version info
Tail: Last 75% via ring buffer — captures results, errors (highest entropy)
Ring buffer: O(1) write, O(C) memory (Cormen et al., CLRS 4th ed.)
Default: 64KB per process. Max memory: 20 × 64KB = 1.28MB

POSIX Process Groups — IEEE Std 1003.1

npm run dev spawns child processes. Sending SIGTERM to the parent doesn't kill children.

Cuba-Exec creates process groups via setsid:

asyncio.create_subprocess_exec(..., start_new_session=True)
os.killpg(os.getpgid(pid), signal.SIGTERM)  # Kills entire tree

Graceful Shutdown

SIGTERM → wait 5s → SIGKILL (if still alive)

Two-phase shutdown (Stevens & Rago, 2013): SIGTERM allows cleanup, SIGKILL is uncatchable.

Configuration

All defaults work out of the box. Override via environment variables:

Setting	Default	Env Var
Max concurrent processes	20	`CUBA_EXEC_MAX_PROCS`
Output buffer size	64KB	`CUBA_EXEC_BUFFER_SIZE`
Idle process TTL	1 hour	`CUBA_EXEC_TTL`
Shutdown timeout	5s	`CUBA_EXEC_SHUTDOWN_TIMEOUT`
Allowed commands	— (all)	`CUBA_EXEC_ALLOWED_COMMANDS`
Blocked commands	25 defaults	`CUBA_EXEC_BLOCKED_COMMANDS`
Allowed directories	— (all)	`CUBA_EXEC_ALLOWED_DIRS`
Audit logging	off	`CUBA_EXEC_AUDIT`

Architecture

cuba-exec/
├── pyproject.toml            # 1 dependency: fastmcp
└── src/
    └── cuba_exec/
        ├── __init__.py
        ├── __main__.py        # Entry point
        ├── server.py          # FastMCP 6 tool definitions (~105 LOC)
        ├── security.py        # SecurityPolicy engine (~135 LOC)
        ├── process_manager.py # Lifecycle FSM + signals + TTL (~520 LOC)
        └── output_buffer.py   # Head+Tail ring buffer (~110 LOC)

Total: ~880 LOC. FastMCP SDK handles protocol boilerplate.

Dependencies (1 total)

Package	Purpose
`fastmcp`	MCP protocol server — auto tool schemas from type hints, Pydantic validation

Everything else is Python stdlib: asyncio, os, signal, time, json, re, pathlib.

Part of the Cuba Ecosystem

Project	Purpose
Cuba-Memorys	Persistent memory — knowledge graph, Hebbian learning
Cuba-Thinking	Sequential reasoning — cognitive engine, NLI, MCTS
Cuba-Search	Web search — research, scraping, validation, documentation lookup
Cuba-Exec	Shell execution — process lifecycle, security, bounded output, POSIX signals

Together: memory + reasoning + search + execution — the four pillars of capable AI agents.

Academic References

#	Citation	Used For
1	Yang et al. (2024). "SWE-agent: Agent-Computer Interfaces." NeurIPS	ACI design, output truncation, guardrails
2	Shannon (1948). "A Mathematical Theory of Communication"	Information-theoretic output strategy
3	IEEE Std 1003.1-2024. "POSIX.1: System Interfaces"	Process groups, setsid, signals
4	Cormen et al. (2022). "Introduction to Algorithms." 4th ed.	Ring buffer O(1) analysis
5	Dijkstra (1965). "Cooperating Sequential Processes"	Semaphore concurrency limiting
6	Stevens & Rago (2013). "APUE" 3rd ed.	Process lifecycle, graceful shutdown
7	TOON (2025). "Token-Oriented Object Notation"	95-97% token reduction
8	OWASP (2025). "Top 10 for Agentic Applications"	Security policy design, allowlist/blocklist

License

CC BY-NC 4.0 — Free to use and modify, not for commercial use.

Author

Leandro Pérez G.

GitHub: @LeandroPG19
Email: leandropatodo@gmail.com

Available Tools

6 tools

list_processesA

List all managed background processes with state and metadata.

Returns PID, state, exit code, duration, bytes captured, and command preview for every background process currently tracked by the server.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explicitly discloses the output fields (PID, state, exit code, duration, bytes captured, command preview) and the scope ('currently tracked by the server'). It does not mention side effects, but as a list operation none are expected, and the read-only nature is implied by 'List'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states the exact purpose and scope, the second enumerates the return payload. No filler, no redundancy, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter listing tool with an output schema available, the description covers the purpose, scope, and returned metadata. It is complete and does not leave critical gaps for an agent to invoke or interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description cannot add parameter-level detail beyond the schema. Per the baseline, a parameterless tool receives a 4, and the description does not need to explain anything further.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'List' with a clear resource ('all managed background processes') and includes the type of data returned. It is easily distinguished from siblings like 'status' (likely single process) or 'send_signal' (mutating action).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use this tool: to get an overview of all managed background processes. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to recognize it as the appropriate choice for a full listing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

runA

Execute a shell command synchronously and wait for completion.

Returns exit code, duration, and captured stdout+stderr. Output is bounded by max_output (default 64KB) using head+tail capture.

ParametersJSON Schema

Name	Required	Description	Default
`cwd`	No
`env`	No
`shell`	No
`command`	Yes
`max_output`	No
`timeout_ms`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and discloses key behaviors: synchronous execution, return values (exit code, duration, stdout+stderr), and output bounding via max_output with head+tail capture. It omits timeout behavior and potential side effects, but still provides meaningful transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three tight sentences with no filler. It front-loads the primary purpose and then adds essential return and output-capture details, earning every word.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and the tool is a command runner, the description covers core execution behavior, return values, and output limits. It does not mention timeout semantics or cwd/env/shell usage, but the overall context is reasonably complete for selecting and invoking the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all six parameters. It only explains max_output and implicitly command, leaving cwd, env, shell, and timeout_ms to rely on schema defaults and names. This is insufficient for a 0-coverage schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a shell command synchronously and waits for completion. This specific verb+resource+mode distinguishes it from siblings like start, send_signal, and list_processes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'synchronously and wait for completion' phrase implies when to use this tool versus starting a background process, but the description never explicitly names alternatives or states when not to use it. Usage context is mostly implied rather than direct.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_inputA

Send text to a running process's stdin.

Use this for interactive processes (REPLs, prompts). The text is encoded as UTF-8 and written to the process stdin pipe.

ParametersJSON Schema

Name	Required	Description	Default
`pid`	Yes
`stdin`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses that text is UTF-8 encoded and written to the process's stdin pipe, adding behavioral detail beyond just 'send input'. It doesn't cover error cases, but the core mechanics are transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, immediately states the action, and every sentence adds value. There is no fluff or repetition of schema information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with an output schema. The description covers purpose, usage, and behavioral mechanism. It lacks edge-case details (e.g., process not found), but given the simplicity and output schema, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It implies that 'stdin' is the text and 'pid' is the target process, but it doesn't explicitly define them. It adds UTF-8 encoding detail for stdin, but leaves pid ambiguous, providing only partial semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Send text to a running process's stdin', specifying the verb and resource. It distinguishes from siblings like send_signal (sends signals) and start/run (creates processes) by focusing on stdin input.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'Use this for interactive processes (REPLs, prompts)', providing clear context for when to use. It doesn't mention exclusions or alternatives explicitly, but the context is sufficient to differentiate from siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_signalA

Send a POSIX signal to a process group.

SIGTERM triggers graceful shutdown: SIGTERM → wait 5s → SIGKILL. Valid signals: SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT.

ParametersJSON Schema

Name	Required	Description	Default
`pid`	Yes
`sig`	No		SIGTERM

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a critical escalation behavior ('SIGTERM → wait 5s → SIGKILL') and enumerates valid signals, which goes beyond the bare parameter names. It could mention error handling or permission requirements, but the key behavioral trait is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: one sentence stating the core function, plus two short sentences detailing the SIGTERM escalation and valid signals. Every sentence earns its place with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and an output schema, the description covers the essential behavioral details: the target (process group), the signal options, and the special SIGTERM handling. It does not discuss return values (handled by output schema) or potential errors, but that is acceptable given the low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clarifies that 'pid' refers to a process group (though the parameter name is 'pid'), and it lists the allowed values for 'sig'. The signal list adds meaningful semantics that the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Send a POSIX signal to a process group' with a specific verb and resource. It distinguishes from sibling tools like 'send_input' (which sends input) and 'status' (which reports status), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for sending signals to process groups and lists valid signals, but it does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool names are mentioned, so usage context is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

startA

Start a background process and return its PID.

The process runs asynchronously. Use status() to check output, signal() to send signals, and input() to send stdin.

ParametersJSON Schema

Name	Required	Description	Default
`cwd`	No
`env`	No
`shell`	No
`command`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses key behaviors: async execution, PID return, and pointer to lifecycle tools. But it omits details like error handling, process cleanup, and the exact format of the PID return value. This is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the primary action. Every sentence adds value: the action, the async nature, and the follow-up tools. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (4 params, 1 required) and presence of an output schema, the description covers the main use case and points to related tools. It could include parameter details, but the lifecycle guidance and async disclosure make it fairly complete for a start tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not explain the parameters. Only 'command' is implicitly understood, while cwd, env, and shell are left entirely undocumented. The description fails to compensate for the lack of schema-level descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Start a background process and return its PID.' It distinguishes from siblings by emphasizing 'background' and 'asynchronously', which contrasts with the 'run' tool and the post-start lifecycle tools (status, signal, input).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context: start a background process, then use status(), signal(), and input() for subsequent interaction. It implies this tool is for launching processes, not managing them. However, it doesn't explicitly mention when to use alternatives like run or list_processes, leaving some room for uncertainty.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statusA

Check background process state, exit code, and tail output.

Returns process state (running/completed/timed_out), duration, total bytes captured, truncation status, and recent output.

ParametersJSON Schema

Name	Required	Description	Default
`pid`	Yes
`tail_bytes`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It explicitly discloses the return fields and possible process states (running/completed/timed_out), which goes beyond the schema. It does not mention error behavior, but for a read-only status check, the non-mutating nature is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main verb. The first sentence states the action and object, the second lists key return fields. There is no redundancy or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple status tool with two parameters and an output schema, the description covers the main behavioral aspects and return values. It omits error handling (e.g., invalid pid) and the precise effect of 'tail_bytes', but these are minor gaps given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no parameter descriptions (0% coverage). The description does not explain the 'tail_bytes' parameter or its relationship to output; it only mentions 'tail output' and 'recent output' without connecting them to the parameter. 'pid' is self-explanatory, but 'tail_bytes' is under-specified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Check') and identifies the resource ('background process state, exit code, and tail output'). It also enumerates return values (running/completed/timed_out, duration, total bytes captured, truncation status, recent output), making the tool's purpose unambiguous and distinguishing it from siblings like run, start, send_signal, send_input, and list_processes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (checking background process status) but does not explicitly mention alternatives or exclusions. Sibling tool names make the differentiation evident, yet there is no direct 'use this instead of that' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv2.0.0Aug 10, 2026
- First observedlist_processes
- First observedrun
- First observedsend_input
- First observedsend_signal
- First observedstart
- First observedstatus

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-08-10 06:50 across 6 tools

Disambiguation5/5

Each tool targets a distinct operation: foreground execution, background start, status query, signal sending, stdin input, and process listing. No overlap in purpose, and the descriptions make the boundaries clear.

Naming Consistency3/5

There is a mix of conventions: 'status' is a noun, 'run' and 'start' are bare verbs, while 'send_signal', 'send_input', and 'list_processes' follow verb_noun. The send_* and list_* group is consistent, but the others break the pattern.

Tool Count5/5

Six tools cover the core process execution and management workflow without unnecessary bloat. The count feels well-scoped for this domain.

Completeness5/5

The set provides complete lifecycle coverage: synchronous execution, background starts, status checks, signal handling, stdin interaction, and process enumeration. No obvious gaps for a process execution server.

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
agentguard A
io.tooloracle
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
Security Monitoring
2
pronto-stream A
io.github.nmxmxh
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Agent Orchestration Cryptocurrency Finance
151
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2

Related MCP Servers

Shell-MCP
Shell Access Command Line Code Execution
kevinwatt
A
license
B
quality
D
maintenance
A secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.
Updated 2 years ago (2025-02-20 18:14 UTC)
20
389 npm
7
MIT
Shell MCP Server
Shell Access Command Line
odysseus0
A
license
Not graded
quality
D
maintenance
A Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
Updated 2 years ago (2024-12-12 00:12 UTC)
7
MIT
MCP Shell Server
Shell Access Command Line Autonomous Agents
mkusaka
A
license
B
quality
F
maintenance
A server that uses the Model Context Protocol (MCP) to allow AI agents to safely execute shell commands on a host system.
Updated a year ago (2025-04-20 12:50 UTC)
1
167 npm
9
MIT
terminal-mcp
ParthKapoor-dev
F
license
Not graded
quality
Not graded
maintenance
A secure and pluggable MCP server to run terminal commands on your local machine or cloud server — remotely, safely, and with LLMs or agentic clients.
Updated a year ago (2025-07-22 01:12 UTC)
-

🚀 Cuba-Exec

Why Cuba-Exec?

Quick Start

1. Prerequisites

2. Install

3. Configure your AI editor

The 6 Tools

run — Execute and wait

start — Background process

status — Check background process

send_signal — POSIX signals

send_input — stdin pipe

list_processes — Process discovery

🛡️ Security Policy Engine

Security Layers

Default Behavior (Zero Config)

Production Hardening

Shell Operator Bypass Prevention

Audit Log (stderr)

Output Format (TOON)

Error Codes

Head+Tail Output Buffer — Shannon (1948)

POSIX Process Groups — IEEE Std 1003.1

Graceful Shutdown

Configuration

Architecture

Dependencies (1 total)

Part of the Cuba Ecosystem

Academic References

License

Author

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`run` — Execute and wait

`start` — Background process

`status` — Check background process

`send_signal` — POSIX signals

`send_input` — stdin pipe

`list_processes` — Process discovery