swarmexec › Docs › MCP server for AI assistants
MCP server for AI assistants_
Swarm access for an AI assistant, per service, by label — read-only except for an opt-in command.
mcp — let an AI assistant inspect the swarm
swarmexec mcp is a Model Context Protocol server on
stdin/stdout. An AI assistant such as Claude Code can then look at the swarm
through the same two channels every other command uses — the manager API and the
node agents — on any Docker context, ssh:// included. It reads
status, tasks, logs and resource usage, diffs and checks stack files, and, where
you allow it, runs a single non-interactive command in a container. Apart from
that one tool (exec_run, off unless a service's labels allow it, and
a command can of course change whatever it can reach) it changes nothing.
See the recipe: let Claude inspect your swarm.
Every tool takes an optional context argument; without it the server
uses the context it was started with (--context,
DOCKER_CONTEXT, DOCKER_HOST, docker's current context).
Connections are kept per context for the session, as the TUI does on a context
switch.
Only the contexts you allow. The assistant gets the context the
server was started with, plus those named with --contexts — nothing
else. Every other context on the workstation, production included, does not exist
for it: contexts_list leaves it out, name and address, and naming it
answers unknown docker context, exactly like a name that does not exist.
| Tool | Answers | Needs |
|---|---|---|
contexts_list | the Docker contexts the assistant may use (see --contexts), and which one the server uses | — |
cluster_overview | nodes, and replica and health state of the visible services — on the command line status | — |
services_list | like ps: mode, replicas, image, ports, stack and running containers | enable |
service_inspect | one service's configuration and its recent tasks | enable |
logs_read | recent logs: tail, since, regexp and minimum level, capped; never follows; when every stream fails the call is an error result (isError), when only some do the lines that arrived come back with a note | logs |
stats | live CPU, memory and healthcheck state per container; waits a few seconds for an agent that has not been asked for a while — on the command line stats | enable |
volumes_list / networks_list / secrets_list / configs_list | names only, and only those the visible services use; networks_list adds each network's subnets and the subnet overlap findings (node IPs inside — as a count, underlay or network overlap — another network named only if visible) with the fix; with endpoints: true it also asks every node's agent (network.inspect) and adds per node the running tasks, local containers, load-balancer endpoints, MACs and networkdb entries, plus stale address candidates and duplicates — all counted over the visible services only: a hidden service's tasks and endpoints count nowhere and never show up as stale or duplicate, a leftover of a removed service is listed without its name; node hostnames only, never node addresses | enable |
stack_diff / stack_check | what deploying a stack file would change / what the deploy check finds — nothing is deployed; on the command line stack diff / stack check | enable on every service of the file |
security_report | the security report, limited to the visible services and what they use | --allow report |
doctor | manager and agent health, as doctor | — |
exec_run | one command, no TTY, no stdin, with a timeout (timeout_seconds, default 30, at most 300; a command still running then comes back as “the command did not finish within …”) and an output cap | exec |
Access: service labels
What the assistant may see is decided per service by service
labels — in a compose file, deploy.labels, the way Traefik is
configured in Swarm mode. Nothing is visible by default.
-
Opt-in. A service without
swarmexec.mcp.enabledoes not exist for the assistant.--default listmakes unlabelled services visible (listed, inspected, their stats read) — never their logs, never exec.read, its old name, is still accepted. -
An explicit
"false"always wins, over the default and over the other labels. A value that is neither true nor false counts as false. -
An unknown key under
swarmexec.mcp.— a typo such asswarmexec.mcp.exce— grants nothing and is written to the log file as a warning; so is an access label set as a container label. -
A service it may not see is indistinguishable from one that does not
exist: the same no such service, absent from every list, count
and stack diff. A visible service without
logsorexecanswers a plain not permitted.
| Flag | Default | Description |
|---|---|---|
--default | none | access for services without swarmexec.mcp.enable: none or list (read is accepted for list) |
--allow | — | optional tools: report adds security_report |
--connect-timeout | 10s | timeout for connecting to an agent |
--contexts | — | further Docker contexts the assistant may use, besides the one the server starts with; a comma list or repeated. A name that is not a context fails at startup |
Security notes
- The labels are invisible to the assistant. They are removed from everything it receives — inspect, lists, task details, stack diffs and checks, error messages — from service and container labels alike, and every result passes one last filter on the way out. It can infer its access from what works, which is accepted.
-
They cannot be changed through MCP. No tool deploys, updates or
edits a service, a stack or a label; the only tool that is not read-only is
exec_run, and only for a service that hasswarmexec.mcp.exec. Any future one has to pass a guard that compares the service before and after the change and refuses if an access label would be added, changed or removed. -
A service that can reach the Docker daemon is never exec'd into,
whatever its labels say: the Docker socket bound in (the security scan's rule),
a bind of the directory it lives in, the Windows pipe, and the swarmexec agent
itself. A service that reaches the daemon another way is refused too: a
DOCKER_HOSTin its environment (current or previous spec), or a network shared with a Docker socket proxy (an image namedsocket-proxyordocker-proxy; hidden services count). Through the socket, anything could relabel any service. The agent's own authorization policy still applies on top. -
Prompt injection. Log lines and command output are written by
the applications. Anyone who can get text into a log can put instructions in
front of the assistant; treat
logsandexecas access for whoever writes to those logs, too. -
Data goes to the model provider. Whatever a tool returns is sent
to the assistant's model. Masking is wider than the scan's rule: values of
environment variables and labels whose names look like credentials
(
PASSWORD,TOKEN,KEY,DSN,AUTH,basicauth, …,_URLincluded) are masked, and so is the credential part of any value that looks like one — the password inscheme://user:pass@host(the rest stays), a JWT, a PEM private key, an htpasswd hash, apassword=…pair — in env, labels, commands and arguments (--requirepass x). It works from shapes, so an unusual format can still get through. Secrets and configs are listed by name only, and every result is capped in size and says when it was cut — but log lines and command output are passed as they are. -
Masking is cosmetic once
execis granted. A command run in the container can print its environment and read its mounted secrets (env,cat /run/secrets/…), so the masking in inspect, diff and check results protects nothing on a service withswarmexec.mcp.exec. Grantexeconly where the assistant — and the model provider — may see everything the container sees. -
The labels and
--contextslimit the MCP channel, not the machine. An assistant that also has a shell on the operator's machine (the documented setup isclaude mcp add …for Claude Code) can runswarmexec execordocker --context …itself, with the operator's credentials. Restrict that shell separately if it matters. -
Audit. The operator reported to the agents is
<you>+mcp, so the audit log shows which actions the assistant took. With mTLS the certificate's CN decides the identity; give the assistant a client certificate of its own to tell it apart there. -
ssh cannot ask. stdin and stdout carry the protocol, so ssh runs
in batch mode: a passphrase-protected key must be loaded in
ssh-agent, and a host key must already be inknown_hosts. The error says which. Logging goes to the log file, never to stdout. - An assistant working in the repository can read the labels straight from the compose file — they are hidden from the server's answers, not secret.