Allows managing Apple containers (VM-isolated sandboxes) on macOS, providing tools for running, executing, listing, and managing container lifecycle, images, and system status.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@container-mcp run a container with Ubuntu and execute 'uname -a'"
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.
Run AI agents in real VM sandboxes on your Mac — fully local, safe by default.
An MCP server for Apple containers — every container gets its own VM, which makes it the right isolation boundary for code an AI agent wrote five seconds ago. No daemon, no account, no cloud.
Part of a larger toolkit: a native macOS "mission control" GUI for agent sandboxes is in development.
Requirements — read before installing. This server shells out to Apple's
container CLI, which only runs on Apple silicon Macs (M-series) on macOS 26
or newer. There is no Linux, Intel, or pre-26 fallback — the server will
install but every tool call fails without a working container CLI.
Apple silicon Mac (arm64)
macOS 26 (Tahoe) or newer
Node.js 20+
Verify the CLI is present before going further: container --version
Real VM isolation, per container — each sandbox gets its own kernel via Apple's container runtime: the right boundary for agent-written code, not a shared-kernel namespace
Local-first and private — no daemon, no account, no cloud; network is denied by default, so nothing leaves your Mac unless you allow it
Safe by default, and visible — explicit mount allowlist, default-deny network, and managed-label scoping; the boundary is meant to be seen, not buried in config
Self-healing errors — every failure tells the agent how to fix it
Agent-aware — every container is labeled with the session and client that created it
Related MCP server: sandbox-mcp
Meets the requirements above? Install with one command (no clone, no build):
claude mcp add container -- npx -y container-mcpOr point any MCP client's config at the published binary:
{
"mcpServers": {
"container": { "command": "npx", "args": ["-y", "container-mcp"] }
}
}git clone https://github.com/mustafaTokmak/container-mcp.git
cd container-mcp
npm install && npm run build
claude mcp add container -- node "$(pwd)/dist/index.js"After adding the server, confirm the toolchain end-to-end by asking your agent to check (and start) the container system service:
Use the system_status tool with start: true.A healthy setup returns running (or container system service started on first
start). An error here means the container CLI isn't installed or you're not on
macOS 26+ — fix that before trying other tools.
Ask your agent to run untrusted code in a throwaway VM and hand back the output — no daemon, no cloud, network denied by default:
Run python:3.12-alpine in a container with wait: true and
command ["python", "-c", "print(sum(range(1000)))"]. Show me the output.The agent calls run_container with wait: true, the code executes inside its
own VM with no network access, and you get back a structured result:
499500That container had its own kernel, couldn't reach the network, and is gone when
you remove it (remove_container) — the right blast radius for code an agent
wrote five seconds ago. Want it to reach the network? Add network: true to the
same request.
Tool | Description |
| Run an image in its own VM (labeled, resource-limited; |
| Run a command in a running container (returns structured |
| Inspect state and output |
| Snapshot CPU, memory, and I/O usage for a running container as JSON |
| Full container detail (configuration, mounts, labels, network, status) as JSON |
| Lifecycle |
| Copy between host and container |
| Image management |
| Remove images to reclaim disk |
| Check/start the container system service |
Env var | Default | Effect |
| launch dir + private scratch dir | Colon-separated allowlist of host paths agents may mount, copy to/from, or build from. Setting it replaces the default. |
| off |
|
| off |
|
|
| CPU limit applied when the agent does not specify one |
|
| Memory limit applied when the agent does not specify one |
|
| Value of the |
|
| Base CLI timeout in ms. Image pulls/builds and wait-mode runs get 600000 automatically. |
|
| Maximum concurrent containers run_container will create |
| off |
|
Mount sources, build contexts, and dockerfiles must exist and are fully
canonicalized (symlinks resolved) before allowlist checks — a path cannot be
swapped for a symlink after validation. A launch directory of / or your home
directory is never used as an implicit allowlist root. Lifecycle tools
(stop, remove, exec, logs, copy) only operate on containers this server
created (tagged dev.container-mcp.managed=true) unless
CONTAINER_MCP_ALLOW_UNMANAGED is set. Every agent-supplied value that
reaches the CLI is guarded against flag injection, and commands are executed
with execFile (no shell), so there is no shell injection surface.
Containers have no outbound network by default (run with --network none); set
CONTAINER_MCP_ALLOW_NETWORK or pass network: true per run to enable egress.
Every container is labeled with a per-session id and the connecting MCP client's
name (dev.container-mcp.session, dev.container-mcp.client) so a session view
can attribute containers truthfully across concurrent agents.
These were doc-only assumptions; the live suite now runs against container 1.0.0 on macOS 26 and confirms (or corrected) each:
container exec takes no -- terminator — Apple captures everything after the
container id as the process argv verbatim (passing -- makes -- the target
executable and fails). Corrected 2026-06-14; a leading-dash command token is treated
as a literal executable and fails closed, so dropping -- opens no flag-injection path.
container cp round-trips a file host → container → host. ✅ confirmed.
container inspect nests labels under configuration.labels; managed-label checks
parse it tolerantly and fail closed (override: CONTAINER_MCP_ALLOW_UNMANAGED). ✅ confirmed.
container run --network none disables egress (the none value is accepted). ✅ confirmed.
Each has a dedicated test in the live suite below.
npm install
npm test # unit + integration suite; no container CLI required
npm run buildCONTAINER_MCP_LIVE=1 npm test additionally runs the live end-to-end suite
(test/live.test.ts), which requires the container CLI,
pulls alpine:latest, and creates real containers. It is the pre-release
gate that verifies the known assumptions above against real hardware. CI
runs the regular suite on macOS for every push.
MIT
Build an image from a Dockerfile. The build context must be inside an allowed host path.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | Tag for the built image, e.g. myapp:dev | |
| context | Yes | Build context directory on the host | |
| dockerfile | No | Path to the Dockerfile (defaults to context/Dockerfile) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It only reveals the constraint on build context path. Missing details include that building consumes disk space, requires Docker daemon, can be time-consuming, and may have security implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines the purpose, second adds a critical constraint. No filler, every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations, and the description is minimal. For a build operation, more detail about return values, error conditions, and prerequisites would be expected for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning to the parameters beyond what the schema already provides (tag, context, dockerfile).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds an image from a Dockerfile, which distinguishes it from sibling tools like pull_image (registry pull) or remove_image. The verb 'build' combined with 'Dockerfile' makes 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a constraint ('build context must be inside an allowed host path'), which provides some usage context. However, it does not explicitly guide when to use this tool versus alternatives (e.g., pull_image) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the most recent log lines from a container (default: last 100). The tail is applied server-side via the CLI -n flag.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name | |
| tail | No | Number of lines (default 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds that tail is applied server-side and default is 100, but does not specify output format (e.g., timestamp inclusion) or potential truncation beyond line count.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, front-loaded with primary purpose. Every sentence provides distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output format details, but given no output schema and simple tool, it's adequate. No mention of log-driver constraints, but still functional for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both params described), but description adds value by stating default tail value (100) and explaining server-side application via -n flag, exceeding schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'fetch the most recent log lines' with verb and resource. It distinguishes from siblings like list_containers or exec_in_container, and provides default behavior (last 100) and implementation detail (CLI -n flag).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for reading logs, but no explicit guidance on when to use vs alternatives, or when not to use. There are no sibling log tools, so context is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Snapshot CPU, memory, and I/O usage for a container as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint already declares the tool is read-only, so the description does not need to restate safety. It adds value by specifying the output is a JSON snapshot of CPU, memory, and I/O usage. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the action and result without any redundant words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema, clear annotation), the description is complete enough for an agent to understand what the tool does and how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete coverage (100%) for the single parameter 'id' with a clear description. The tool description adds no additional meaning beyond what the schema specifies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'snapshot' and identifies the resource as 'CPU, memory, and I/O usage for a container', clearly distinguishing it from sibling tools like container_logs or inspect_container.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for querying current resource usage but does not explicitly state when to use it versus alternatives like container_logs or inspect_container. No guidance on when not to use is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy files between host and container. Container paths use ':'. Host paths must be inside the allowed roots.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source path (host path or <id>:<path>) | |
| destination | Yes | Destination path (host path or <id>:<path>) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the destructive nature (copy is a write operation) consistent with the destructiveHint annotation. It adds the behavioral constraint about allowed roots, which goes beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and contains no superfluous words. Every sentence adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, the description covers the key aspects: direction (host-container), path format, and constraint. However, it does not mention return values or error cases, which could be useful for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the container path format and host path restriction, providing additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Copy' and the resource 'files between host and container'. This distinguishes it from sibling tools which focus on container management, listing, and logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the format for container paths ('<id>:<path>') and the constraint that host paths must be inside allowed roots, providing clear usage context. However, it does not explicitly state when not to use the tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a command inside a running container and return its output.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name | |
| command | Yes | Command and arguments |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions that the container must be running and that output is returned, but it does not specify whether stdout, stderr, both, exit codes, or error handling are included. Critical behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacking an output schema, the description should clarify the return format (stdout, stderr, exit codes). It does not address error handling, timeouts, or prerequisites. The sibling list is provided but not leveraged for differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both `id` (Container ID or name) and `command` (Command and arguments). The description adds no additional meaning beyond the schema, earning a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Run a command), the resource (inside a running container), and the output (return its output). It distinguishes the tool from siblings like `container_logs` (logs only) and `run_container` (starts a new container).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only states what the tool does, without any explicit context about appropriate use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full container details (configuration, mounts, labels, network, status) as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds context on what is returned (configuration, mounts, labels, network, status) and format (JSON), which is beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. No extraneous words. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter and read-only annotation. Description adequately explains output (JSON with specifics). No output schema, so listing return fields is helpful. Could mention that it returns detailed configuration, but current is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers parameter 'id' with description 'Container ID or name' at 100% coverage. Description adds no additional semantic beyond schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns full container details as JSON, listing specific aspects. Distinct from sibling tools like list_containers or container_logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives, but the purpose implies it's for detailed inspection. Lacks statements like 'Use this to get all details for a single container, rather than list_containers which only shows summary.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List containers as JSON. Pass all: true to include stopped containers.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Include stopped containers |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description adds that the tool returns JSON and that 'all' includes stopped containers. It does not disclose other potential behaviors like pagination or default limits, but for a simple list, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence states the core purpose, and the second handles the optional parameter. It is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional boolean parameter, no output schema, readOnlyHint annotation), the description covers the essential behavior. It could mention the default for 'all' (only running containers) but the current text implies it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the tool description repeats the parameter meaning without adding new depth. This meets the baseline but does not enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'containers', and it specifies that the output is in JSON format. This effectively distinguishes it from sibling tools like list_images, which lists images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance for one parameter ('all: true' to include stopped containers) but does not explicitly state when to use this tool vs. alternatives, or when not to use it. The usage is implied by the nature of the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List local container images as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description does not add any additional behavioral context beyond what annotations convey. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, highly concise with no extraneous information. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and annotations present, the description is minimal. It does not specify the structure of the JSON output or any other details, which would be helpful given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so schema coverage is effectively 100%. The description does not need to add parameter details. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists local container images as JSON. The verb 'list' and resource 'local container images' are specific, and the format 'JSON' is mentioned. This distinguishes it from sibling tools like list_containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or situations where other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove dangling images to reclaim disk. Pass all: true to remove all unused images.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Remove all unused images, not just dangling |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the destructiveHint annotation by explaining the purpose (reclaim disk) and the difference between dangling and all unused images. It does not disclose all behavioral details (e.g., impact on running containers), but provides useful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. First sentence states the purpose and outcome, second sentence gives parameter usage. No wasted words, front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one boolean parameter and no output schema, the description covers the primary behaviors (dangling vs all unused). It lacks explanation of terms like 'dangling' or edge cases, but is sufficient for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'all' parameter with 100% coverage. The description reinforces the parameter's effect but does not add new semantic information beyond what the schema provides. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and resource 'dangling images' with the goal 'to reclaim disk'. It distinguishes itself from sibling 'remove_image' which removes a specific image, while this tool performs bulk removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions how to remove all unused images via 'all: true', and implies the default behavior (remove only dangling). However, it does not explicitly state when not to use the tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull an OCI image from a registry, e.g. 'alpine:latest'.
| Name | Required | Description | Default |
|---|---|---|---|
| reference | Yes | Image reference, e.g. alpine:latest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states the basic action, failing to disclose side effects (storage, network calls, permissions) or whether it overwrites existing images.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words, but it could include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the basic action and example but lacks completeness: no mention of errors, auth, or network dependencies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter description in the schema already defines 'reference'. The description adds the example 'alpine:latest' but no additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (pull an OCI image) and provides a concrete example ('alpine:latest'), effectively distinguishing it from sibling tools like list_images or build_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives (e.g., build_image, remove_image) and omits prerequisites like registry authentication or network requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a container. Pass force: true to delete a running container.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name | |
| force | No | Force-delete even if running |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the destructiveHint annotation by explaining the force option for running containers. It discloses the key behavioral aspect beyond what the annotation alone conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with only two parameters and no output schema, the description provides adequate context. It could mention irreversible consequences more explicitly, but annotations partially cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover both parameters (id and force) fully. The description restates the force behavior, adding minimal new information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a container') and the specific verb-resource combination. It distinguishes from siblings like stop_container by indicating removal versus stopping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use the force parameter, but does not explicitly compare to alternative tools like stop_container or mention prerequisites or situations to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a local image by reference. Pass force: true to remove even if in use.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Force removal | |
| reference | Yes | Image reference, e.g. alpine:latest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals destructive behavior; the description adds the important detail that force:true allows removal even if the image is in use, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words: first sentence states the action, second provides a key conditional. Very concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two fully described parameters and no output schema, the description covers the essential behavior. Could mention potential errors or outcomes, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond what the schema already provides for reference and force.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'a local image by reference', distinguishing it from sibling tools like prune_images for bulk removal or pull_image for adding images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the force parameter for removing images in use, but does not explicitly indicate when to use this tool versus alternatives like prune_images or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a container inside its own lightweight VM. By default runs detached and returns the container ID. Pass wait: true to run to completion and return the container's output (10 minute limit). Mount sources must be inside the allowed host paths. Default CPU/memory limits are applied unless overridden.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Environment variables | |
| cpus | No | CPU limit, e.g. '4' | |
| name | No | Optional container name | |
| wait | No | Run to completion and return the container's output instead of its ID (10 minute limit) | |
| image | Yes | Image reference, e.g. alpine:latest | |
| ports | No | Publish container ports to the host | |
| memory | No | Memory limit, e.g. '4g' | |
| mounts | No | ||
| command | No | Command and arguments to run | |
| network | No | Allow outbound network access (default: denied unless CONTAINER_MCP_ALLOW_NETWORK is set) | |
| workdir | No | Working directory inside the container |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behaviors: detached by default, wait mode with 10-minute limit, mount path restrictions, and default CPU/memory limits. It does not cover cleanup behavior or error states, but adds significant context beyond a basic 'runs a container'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, all essential and front-loaded with the primary action. No superfluous words, and each sentence adds distinct information (detached mode, wait option, mount rules, resource defaults).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, nested objects, no output schema), the description covers key aspects: run mode, output handling, mount constraints, and default resources. It could mention that the container remains running after returning ID, and possibly error handling, but overall it is sufficient for an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (91%), so baseline is 3. The description adds value by clarifying that mount sources must be in allowed paths, default limits apply unless overridden, and the wait parameter's behavior. This provides context beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it runs a container in its own lightweight VM, and distinguishes from sibling tools like list_containers, container_logs, etc., which are for managing existing containers. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the default detached behavior, the wait option for completion, mount constraints, and default resource limits. It provides clear context on when to use the tool, but does not explicitly mention when not to use it or alternative tools like exec_in_container for running commands in existing containers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running container.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states 'Stop a running container' without detailing side effects (e.g., container state becomes 'exited', can be restarted, sends SIGTERM then SIGKILL), required permissions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (4 words), which is concise but at the cost of missing critical details. It is front-loaded but insufficiently informative for a tool with 15 siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is still incomplete. It omits prerequisites (container must be running), behavior (graceful shutdown, timeout), and the fact that this is part of a container lifecycle. The context provided is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-described 'id' parameter. The description adds no value beyond the schema, which already states 'Container ID or name'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'stop' and the resource 'running container', making the purpose unambiguous. However, it does not explicitly distinguish from sibling tools like 'remove_container', which could confuse an agent about when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'remove_container' or 'exec_in_container'). The absence of contextual hints forces the agent to infer usage from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the Apple container system service is running. Pass start: true to start it if it is stopped.
| Name | Required | Description | Default |
|---|---|---|---|
| start | No | Start the service if it is not running |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description covers the basic behavior (check and start), but does not disclose details such as whether starting is destructive, permissions needed, or the return value format. With no annotations, the description carries full burden but is adequate for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundant words. The main action is front-loaded ('Check whether...'). Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one optional parameter, no output schema), the description is mostly adequate. However, it omits what the tool returns (e.g., a status boolean or message), which is critical for an agent to use the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the 'start' parameter as a boolean to start the service. The description adds little new information ('if it is stopped' vs 'if it is not running'). With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('Apple container system service') and specifies two actions: check status and optionally start. This distinguishes it from sibling tools which operate on individual containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for checking or starting the system service, but does not provide explicit guidance on when not to use it or compare to alternatives. The usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation—containers vs images, lifecycle vs inspection vs logs—with no overlapping functionality. An agent can easily select the correct tool.
All tool names follow a consistent verb_noun pattern using snake_case, e.g., list_containers, run_container, pull_image. Minor variations like container_logs are still clear and predictable.
With 15 tools, the set is well-scoped for container management—covering containers, images, and system status without being overwhelming or sparse.
Covers essential container and image lifecycle operations (CRUD, logs, stats, exec, copy, pull, build, prune). Missing operations like commit or rename are tertiary; the surface is highly functional.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The cloud for agents. Tools for AI agents to register, build, and deploy other agents. Zero human required.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mustafaTokmak/container-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
