What a coding agent needs from Docker
An agent working on a real project keeps asking the same few things: what is running, which app is on port 3000, why did this container die, what do the logs say, can I run the tests somewhere disposable. With only a shell, it answers them by running docker ps, docker inspect and docker logs and reading every line that comes back. That works, and it is slow and expensive: raw JSON and hundreds of log lines go into the model's context on every turn.
An MCP server turns those questions into tools that return the answer itself. Oxcart's tools are shaped like the questions, not like Docker's API endpoints, so one call replaces a chain of commands.
The 13 tools
| Intent | Tools | Lowest level that lists them |
|---|---|---|
| See | status, projects, ports, images, logs | Read only |
| Explain | diagnose: exit codes, OOM kills, failed health checks, port problems and the log lines that matter | Read only |
| Act | container (start, stop, restart), exec, compose (up, down), sandbox without network | Manage |
| Change and tidy | build, remove, cleanup (preview first), sandbox with network | Full |
status shows each Compose project with its folder, git branch and localhost URLs, so “the app on port 3000” means the same thing to you and your agent. Clients that subscribe to resources hear about a crash, an OOM kill or a health change when it happens, without polling.
Smaller answers, cheaper sessions
What an agent reads to answer each question, through Oxcart against the docker CLI output it would read otherwise, measured at the same moment on the same containers:
| Question | Oxcart MCP | docker CLI equivalent | docker CLI | Smaller by |
|---|---|---|---|---|
| Why did this container stop? | 159 | inspect + logs --tail 300 | 2,014 | 13× |
| Any errors in the last 500 log lines? | 39 | logs --tail 500 | 703 | 18× |
| What is running? | 106 | ps -a + stats --no-stream + compose ls -a | 332 | 3.1× |
Five test containers (a crashing one, an unhealthy one, an OOM-killed one, a Compose project, a published port). diagnose and logs stay the same size however long the logs get. The tool list itself costs 510 tokens once per session at the read-only level (6 tools) and 1,463 with all 13.
Whole sessions tell the same story. Claude Code with Claude Opus 5.5 answered two everyday questions, once with only the docker CLI and once with Oxcart's MCP server. Both arms got both answers right.
| Task | Time | Cost | Tokens | Turns |
|---|---|---|---|---|
“Is worker throwing errors? Give me the error.” | 4.2 s vs 31.0 s | $0.022 vs $0.157 | 10,686 vs 52,266 | 2 vs 8 |
“My api container keeps dying. Why?” | 8.5 s vs 14.9 s | $0.036 vs $0.070 | 11,283 vs 19,510 | 2 vs 4 |
One session per task with and without Oxcart, on synthetic test containers, Oxcart 0.1.0: indicative only. Cost depends on prompt caching, and the run order was not alternated.
Set up Oxcart's MCP server in any coding agent
- Install Oxcart. Download Oxcart (Apple silicon, macOS 26 or later) and open it. Setup is offline and takes seconds.
- Copy the setup sentence. Open MCP Integrations in Oxcart's sidebar and copy the sentence: “Set up Oxcart's MCP server for me: run
/Applications/Oxcart.app/Contents/Helpers/oxcart agent setupand follow its instructions.” - Paste it into your agent. Paste it into Claude Code, Codex, Cursor or any agent that can run commands. The agent runs the command, reads the steps for itself, and registers a server named
oxcart. - Ask about your containers. Ask “what is running?” or “why did
apistop?”. The agent appears on the MCP Integrations page, read-only, with every call in its activity log. - Raise the level if you want. Set the agent to Manage to let it start, stop, exec and run Compose, or to Full to let it build, remove and clean up. Block refuses every call.
If your agent can't run commands (Claude Desktop, LM Studio and similar apps), Oxcart shows a JSON snippet to add to the app's MCP settings instead. For Claude Code, the direct command is:
claude mcp add -s user oxcart -- /Applications/Oxcart.app/Contents/Helpers/oxcart mcp --client claude-codeFor Codex, codex mcp add oxcart -- /Applications/Oxcart.app/Contents/Helpers/oxcart mcp --client codex registers the server for the Codex CLI and IDE extension.
Permission levels you set per agent
| Level | The agent can |
|---|---|
| Read only (default) | See containers, logs, ports, projects and images; diagnose failures |
| Manage | Also start, stop and restart, run commands, Compose up and down, run sandboxes without network |
| Full | Also build, remove and clean up, and give sandboxes network access |
| Block | Nothing: no tools listed, every call refused, and the agent is told why |
Tools above an agent's level are not listed at all, which also keeps its context smaller. Every call is logged on your Mac and shown on the MCP Integrations page; nothing leaves the Mac. The levels govern what Oxcart's tools do for an agent. They are not a sandbox: an agent that can run shell commands can still run docker itself, so pair them with your agent's own command permissions.
Agents with setup steps
Claude Code, Claude Desktop, Codex, Cursor, VS Code with Copilot, Devin Desktop, Zed, Gemini CLI, GitHub Copilot CLI, OpenCode, Cline, Junie, JetBrains AI Assistant, Goose, Kiro, Amp, Warp and LM Studio, plus a step for any other MCP client. The steps come from your installed copy of Oxcart (oxcart agent setup), with your Mac's real paths, so they work offline and match your version.
Containers for agent workflows beyond MCP
- Dev Containers: run the agent inside a Dev Container so its shell, tools and network stay in the project's container. Oxcart runs the Dev Containers CLI; see Dev Containers and Testcontainers on a Mac.
- Fast inner loop: agents run and tear down containers constantly. Oxcart measured 42 ms for
docker run --rmand 77 ms to stop and remove 20 containers, fastest of the three runtimes we tested (comparisons). - Compose stacks: the agent's
composetool brings projects up and down at the Manage level; see Docker Compose on Apple silicon.
Questions
Is there an MCP server for Docker containers on the Mac?
Yes. Oxcart includes one: oxcart mcp, a local stdio MCP server with 13 tools for status, diagnosis, logs, ports, images, exec, Compose, builds, sandboxes and cleanup. It listens on no network port and needs no token.
How do I connect Claude Code to my Docker containers?
Paste Oxcart's setup sentence into Claude Code, or run claude mcp add -s user oxcart -- /Applications/Oxcart.app/Contents/Helpers/oxcart mcp --client claude-code. Claude Code then lists the oxcart server and can call its tools.
Does it work with Codex, Cursor and VS Code with Copilot?
Oxcart has setup steps for 18 named clients, including Codex, Cursor, VS Code with Copilot, Claude Desktop, Zed, Gemini CLI, GitHub Copilot CLI, Cline, Goose, Kiro, Amp, Warp and LM Studio, and a generic step for any other MCP client. Claude Code is the client that was run end to end.
Can the agent delete my containers or volumes?
Not by default. Every agent starts read-only. You can raise an agent to Manage or Full, or Block it, per agent. At Full, cleanup first returns a preview and a token, and deletes only what that preview listed. The levels govern Oxcart's tools; they are not a sandbox, so an agent with shell access can still run the docker CLI directly.
Why not just let the agent run docker commands?
It works, but the agent reads a lot of raw output. Answering "why did this container stop?" took 159 tokens through Oxcart's diagnose tool against 2,014 for docker inspect plus docker logs --tail 300: 13× smaller. In one Claude Code session per task (indicative), finding an error in the logs took 4.2 s instead of 31.0 s.
Does the MCP server send my data anywhere?
No. It talks only to the local engine socket and makes no network connection of its own. Every call is written to an activity log on your Mac. Images are still pulled from registries when a tool starts or builds something that needs them, as docker run would.
Can my agent run code in a throwaway container?
Yes, with the sandbox tool: a throwaway container with no network unless the agent is at the Full level and asks for it, limited to 2 GiB of memory and 1,024 processes.
Sources and method
- Answer sizes: measured on 2026-10-10 with five test containers; tokens estimated as characters ÷ 4.
- Sessions: Claude Code 2.1.296 with
claude-opus-5-5, Oxcart 0.1.0, one run per task and arm. - Speed figures: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, 8 CPUs and 12 GiB; the comparison runtimes were measured earlier the same day on the same Mac and harness with the docker 29.4 client.