XenMCP Docker agent

A small, read-only MCP server for the containers on one Docker host. Run it next to your containers, put it behind your reverse proxy, and connect it to Claude, Cursor or VS Code through XenMCP: every person signs in on their own (OAuth), access can be revoked at any time, and every call is in the journal.

It can see, never change:

There is no tool that starts, stops, restarts, removes, execs, builds or pulls. The agent sends Docker only a short list of GET requests (lib.mjs, allowedPath) and refuses everything else before it leaves the process.

Install

1. In the XenMCP panel: Add server → Docker agent. It shows a key and the command below with the key filled in.

2. On your Docker host:

docker run -d --name xenmcp-docker-agent --restart unless-stopped \
  --read-only --cap-drop ALL --security-opt no-new-privileges --memory 128m \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e XENMCP_AGENT_KEY=<the key from the panel> \
  -p 127.0.0.1:8090:8080 \
  ghcr.io/xenmcp/docker-agent:1.0

3. Make it reachable over HTTPS through your reverse proxy (below), e.g. https://docker-agent.example.com/mcp.

4. In the panel: enter that address and press Check and save.

Or with Docker Compose:

services:
  xenmcp-docker-agent:
    image: ghcr.io/xenmcp/docker-agent:1.0
    restart: unless-stopped
    read_only: true
    cap_drop: [ALL]
    security_opt: [no-new-privileges:true]
    mem_limit: 128m
    group_add: ["${DOCKER_GID}"]   # stat -c %g /var/run/docker.sock
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      XENMCP_AGENT_KEY: ${XENMCP_AGENT_KEY}
    ports:
      - 127.0.0.1:8090:8080

Related MCP server: dockhand-readonly-mcp

Reverse proxy

The agent listens on plain HTTP; your proxy adds HTTPS. It must pass X-Forwarded-For (all three below do).

Caddy

docker-agent.example.com {
  reverse_proxy 127.0.0.1:8090
}

nginx

server {
  listen 443 ssl;
  server_name docker-agent.example.com;
  # ssl_certificate …; ssl_certificate_key …;
  location /mcp {
    allow 46.225.57.217;   # XenMCP
    deny all;
    proxy_pass http://127.0.0.1:8090;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 120s;
  }
}

Traefik (labels on the agent container, without ports)

labels:
  - traefik.enable=true
  - traefik.http.routers.xenmcp-agent.rule=Host(`docker-agent.example.com`) && PathPrefix(`/mcp`)
  - traefik.http.routers.xenmcp-agent.tls.certresolver=letsencrypt
  - traefik.http.services.xenmcp-agent.loadbalancer.server.port=8080

Without XenMCP

The agent is a plain MCP server (Streamable HTTP at /mcp), so any client that can send a header works. Set XENMCP_ALLOW_IPS to the addresses that may call it (* for any, only behind your own proxy or firewall) and send the key as Authorization: Bearer <key>. Without XenMCP there is no per-person sign-in and no journal: everyone with the key has the same access.

It is listed in the official MCP Registry as com.xenmcp/docker-agent (server.json in this repository).

Settings

Hide single containers with the label xenmcp.hide=true: they are left out of every answer.

Good to know

• Logs are what Docker keeps: with the default json-file driver everything since the container was created, unless you set max-size/max-file. A recreated container starts with an empty log. For history beyond that, use Grafana + Loki.

• Logs can contain personal data and secrets. What a tool returns goes to the AI client you connect (for Claude: Anthropic). Hide containers you do not want to share.

• The socket is mounted read-only, but Docker's API does not know read-only mounts — the limit is the agent's own allow-list, which is why it is small, open source and tested (npm test, npm run e2e).

Develop

npm ci
npm test        # unit tests
npm run e2e     # against your local Docker (starts and removes three busybox containers)

Questions and feedback

Ask in the XenMCP community on Discord (forum #help, tag docker-agent) or open an issue here. Security issues: security@xenmcp.com, not in public.

MIT licence. Made by Xenaxio for XenMCP.