Docker MCP Setup: OpenCode | AgenticSkillset.org

OpenCode là AI coding agent CLI mã nguồn mở, cho phép bạn cắm vào nhiều LLM provider khác nhau (Anthropic, OpenAI, hay model chạy local qua Ollama) thay vì bị khoá cứng vào một nhà cung cấp. Vì kiến trúc mở này, cách OpenCode khai báo MCP server có vài điểm khác biệt so với Claude Code mà bạn cần nắm rõ trước khi copy-paste config từ nơi khác sang.

Bài này đi qua cách cài Docker MCP cho OpenCode, cách dùng nó để quản lý image/container/compose stack hàng ngày, một ví dụ debug thực tế container bị crash loop, và cuối cùng — vì OpenCode hỗ trợ đa dạng model backend — những giới hạn thực tế bạn nên biết trước khi tin tưởng hoàn toàn vào agent.

Cài Đặt Và Kết Nối Docker MCP Với OpenCode

OpenCode đọc cấu hình MCP từ file opencode.json hoặc opencode.jsonc (bản hỗ trợ comment, nên dùng để dễ maintain) ở root project, hoặc file config global tại ~/.config/opencode/opencode.json nếu bạn muốn dùng chung cho mọi project.

Trước tiên, đảm bảo Docker CLI đã cấu hình đúng và Docker MCP Toolkit (hoặc server tương đương) đã cài:

docker --version
docker mcp --version

Thêm block mcp vào opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docker": {
      "type": "local",
      "command": ["docker", "mcp", "gateway", "run"],
      "environment": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      },
      "enabled": true
    }
  }
}

Vài điểm khác biệt quan trọng so với format Claude Code/Cursor mà bạn dễ gõ nhầm khi copy config:

command là một mảng (array) gồm executable và toàn bộ args gộp chung, khác với format command + args tách riêng ở nhiều client khác.
Key truyền biến môi trường là environment, không phải env — gõ nhầm key này là nguyên nhân phổ biến nhất khiến server "load được nhưng không kết nối đúng Docker context".
enabled: true cần khai báo rõ ràng ở một số phiên bản OpenCode, mặc định server có thể bị disable nếu thiếu field này.

Nếu bạn build MCP server riêng chạy trong container (thay vì dùng Docker MCP Toolkit có sẵn), cần mount socket vào đúng container đó:

{
  "mcp": {
    "docker-custom": {
      "type": "local",
      "command": [
        "docker", "run", "--rm", "-i",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "my-org/docker-mcp-server:latest"
      ],
      "enabled": true
    }
  }
}

Sau khi lưu config, chạy OpenCode và kiểm tra:

opencode

Trong phiên làm việc gõ /mcp để xem trạng thái server, hoặc chạy với log chi tiết nếu cần debug:

opencode --log-level debug

Nếu server báo error hoặc disconnected, các nguyên nhân thường gặp: sai cú pháp JSON (thiếu dấu phẩy — nên dùng jsonc để debug dễ hơn), Docker daemon chưa chạy, hoặc user hiện tại không nằm trong group docker nên không có quyền truy cập socket.

Sự khác biệt về tool-calling giữa các LLM backend

Vì OpenCode cho chọn model tuỳ ý, khả năng gọi đúng tool Docker MCP sẽ khác nhau đáng kể theo model. Model mạnh về function calling (Claude, GPT-4 class) thường gọi đúng tool và parse JSON kết quả ổn định; model nhỏ hơn hoặc chạy local có thể gọi sai tham số, hoặc tệ hơn — tự "bịa" ra kết quả list container thay vì thực sự gọi tool. Luôn test bằng một prompt đơn giản trước khi giao việc quan trọng.

Mẹo: Sau khi cấu hình xong, yêu cầu OpenCode chạy một task rất đơn giản như "list toàn bộ image hiện có, sắp xếp theo size" — nếu kết quả khớp với thực tế bạn biết, coi như cả kết nối MCP và khả năng tool-calling của model đang chọn đều ổn.

Quản Lý Image, Container Và Compose Stack Từ OpenCode

Sau khi kết nối ổn định, phần lớn công việc hàng ngày với Docker MCP trong OpenCode xoay quanh ba nhóm: quản lý image, quản lý container, và điều khiển compose stack.

Quản lý image

Liệt kê toàn bộ image local, kèm tag, size, created time. Đánh dấu
image nào không có tag nào tham chiếu tới (dangling image) và image
nào cũ hơn 30 ngày chưa được pull lại.

Agent gọi list_images, lọc theo điều kiện, và trả về bảng tổng hợp — nhanh hơn nhiều so với tự chạy docker images -a rồi lọc bằng mắt.

Quản lý container

Container nào đang chạy hiện tại đang restart nhiều hơn 3 lần trong
10 phút qua? Với mỗi container như vậy, lấy 50 dòng log cuối và exit
code của lần crash gần nhất.

Đây là pattern debug bạn sẽ dùng lại nhiều lần: agent tự chuỗi list_containers (lọc theo restart_count) → inspect_container (lấy exit code) → get_logs (lấy log gần nhất) — ba bước bạn thường làm tay bằng docker ps, docker inspect, docker logs riêng lẻ.

Điều khiển Compose stack

Với project dùng compose.yaml, agent có thể quản lý cả stack thay vì từng container riêng:

Trong compose stack tại thư mục hiện tại, service nào đang không
"healthy" hoặc chưa start? So sánh với định nghĩa trong compose.yaml
để xem service nào bị thiếu hoặc chạy sai image tag.

Agent gọi compose_ps để lấy trạng thái thực tế, đọc file compose.yaml (nếu bạn đã cho phép đọc file trong session), và so sánh drift — rất hữu ích khi bạn onboard vào một project có compose stack phức tạp, nhiều service phụ thuộc nhau.

Bảng các nhóm tool Docker MCP bạn sẽ gọi nhiều nhất qua OpenCode:

Nhóm	Tool tiêu biểu	Dùng khi nào
Image	`list_images`, `build_image`, `pull_image`	Dọn dẹp, rebuild, kiểm tra version
Container	`list_containers`, `inspect_container`, `get_logs`	Debug crash, kiểm tra config runtime
Compose	`compose_up`, `compose_down`, `compose_ps`	Quản lý multi-service stack
Dọn dẹp	`prune`, `remove_image`, `remove_container`	Giải phóng disk, luôn cần xác nhận trước khi chạy

Mẹo: Khi giao task quản lý compose stack cho agent, luôn yêu cầu nó liệt kê rõ service nào sẽ bị ảnh hưởng trước khi chạy compose_down hoặc compose_up --force-recreate — lệnh này có thể làm mất state của service khác trong cùng stack mà bạn không định đụng tới.

Ví Dụ Thực Tế: Debug Container Bị Crash Loop Trong OpenCode

Container crash loop (liên tục restart) là một trong những use case Docker MCP toả sáng nhất, vì nó đòi hỏi kết hợp nhiều nguồn thông tin — status, exit code, log, resource limit — mà nếu làm tay sẽ mất vài phút ghép lại, còn agent làm trong một lượt.

Giả sử bạn nhận báo cáo: service worker trong compose stack cứ restart liên tục. Prompt đầy đủ:

Container "worker" đang restart liên tục. Hãy điều tra:
1. Lấy trạng thái hiện tại và số lần restart (restart count).
2. Lấy exit code của lần crash gần nhất qua inspect_container.
3. Lấy 100 dòng log cuối của container này.
4. Kiểm tra resource limit (CPU/memory) hiện tại của container, và
   memory usage tại thời điểm gần crash nhất nếu có dữ liệu.
5. Kết luận nguyên nhân khả năng cao nhất, kèm bằng chứng cụ thể
   (dòng log, exit code, số liệu resource).

Agent chuỗi các tool call: list_containers xác nhận restart count cao → inspect_container lấy exit code (ví dụ 137 là dấu hiệu OOM-killed, 1 thường là lỗi runtime application, 139 là segmentation fault) → get_logs đọc traceback cuối cùng trước khi crash → get_stats (nếu server hỗ trợ) kiểm tra memory usage.

Ví dụ báo cáo agent có thể trả về:

Container "worker" exit code 137 ở lần crash gần nhất (3 lần trong
10 phút qua). Memory limit hiện tại: 256Mi. Log cho thấy heap tăng
liên tục từ 180Mi lên 254Mi trong 40 giây trước khi bị kill, không
có error log rõ ràng nào khác.

=> Kết luận: container bị OOM-killed do memory limit quá thấp so với
nhu cầu thực tế của process, không phải lỗi logic application.
Đề xuất: tăng memory limit lên tối thiểu 512Mi trong compose.yaml,
đồng thời kiểm tra process có đang leak memory (heap tăng liên tục
không giảm) hay đây là mức dùng bình thường khi tải cao.

Đây là kiểu kết luận có bằng chứng cụ thể (exit code, số liệu memory, log timeline) mà bạn có thể tin tưởng và hành động ngay, khác với một câu trả lời chung "có thể do thiếu resource".

Mẹo: Với exit code, luôn yêu cầu agent giải thích ý nghĩa cụ thể (137 = SIGKILL thường do OOM, 143 = SIGTERM, 1 = lỗi application) thay vì chỉ báo số — nhiều exit code có ý nghĩa kỹ thuật rõ ràng giúp khoanh vùng nguyên nhân ngay từ bước đầu.

Những Hạn Chế Của Docker MCP Trong OpenCode

Docker MCP trong OpenCode mạnh nhưng có một số giới hạn thực tế, phần lớn xuất phát từ chính kiến trúc đa-provider của OpenCode chứ không phải từ Docker MCP server.

Hạn chế	Biểu hiện thực tế	Cách khắc phục
Tool-calling không đồng nhất giữa provider	Model nhỏ/local gọi sai tham số, hoặc bịa kết quả thay vì gọi tool thật	Ưu tiên model có function calling tốt cho task Docker quan trọng; luôn test bằng prompt đơn giản trước
Log dài làm tràn context window	Log build hoặc log container hàng nghìn dòng khiến agent bị cắt context hoặc tóm tắt thiếu chính xác	Luôn giới hạn `tail`/`since` khi lấy log, tránh dump toàn bộ log không giới hạn
Session không giữ state Docker context giữa các lần gọi	Agent có thể "quên" context/project đang làm việc nếu session bị reset	Luôn nhắc lại rõ tên container/service trong mỗi prompt, không giả định agent còn nhớ từ câu trước quá lâu
Độ ổn định phụ thuộc version Docker MCP server	Behavior tool có thể đổi giữa các bản Docker MCP Toolkit khác nhau	Pin version cụ thể của Docker MCP Toolkit/CLI trong môi trường CI hoặc dev chung của team
Thiếu UI trực quan xem lại log/inspect	So với VS Code/Cursor có panel riêng, OpenCode CLI thuần terminal khiến việc review output dài hơi bất tiện hơn	Yêu cầu agent tổng hợp output dạng bảng ngắn gọn, xuất phần chi tiết ra file riêng khi cần đọc kỹ

Một điểm cần lưu ý thêm: vì OpenCode có thể chạy với model local qua Ollama, và các model này thường yếu hơn đáng kể ở khả năng suy luận nhiều bước (multi-step reasoning), các task đòi hỏi chuỗi nhiều tool call liên tiếp (như debug crash loop ở phần trước) nên ưu tiên chạy với model cloud mạnh, chỉ dùng model local cho các task đơn giản một bước (list, inspect đơn lẻ).

Mẹo: Nếu team bạn dùng OpenCode với nhiều model backend khác nhau, hãy quy định rõ trong tài liệu nội bộ: model nào được phép chạy task Docker MCP có quyền write/destructive, và model nào chỉ nên dùng cho task read-only — tránh việc một model yếu vô tình gọi sai tool ở bước quan trọng.

Tips

Docker MCP trong OpenCode cho bạn linh hoạt chọn model backend, nhưng chính sự linh hoạt đó cũng là nguồn rủi ro nếu không kiểm soát kỹ. Ghi nhớ các điểm sau khi đưa vào workflow thật:

Luôn dùng opencode.jsonc (có comment) thay vì .json thuần để dễ ghi chú lý do từng config, đặc biệt với field dễ nhầm như environment vs env.
Test tool-calling bằng prompt đơn giản mỗi khi đổi model backend, đừng giả định model mới sẽ hành xử giống model cũ.
Giới hạn tail/since khi đọc log để tránh tràn context window, nhất là với container log lớn.
Với task write/destructive (build, remove, compose down), ưu tiên chạy bằng model mạnh và có bước xác nhận thủ công.
Pin version Docker MCP server cụ thể nếu bạn cần pipeline ổn định lâu dài cho cả team.

Mẹo: Lưu một file docs/opencode-docker-prompts.md trong repo chứa các prompt debug/quản lý Docker đã được kiểm chứng hoạt động tốt với model backend team đang dùng — tiết kiệm thời gian dò lại từ đầu mỗi khi có thành viên mới.