Docker MCP Setup: Cursor | AgenticSkillset.org

Cursor là IDE fork từ VS Code, tích hợp sẵn AI agent mode có thể gọi MCP tool trực tiếp trong lúc bạn đang sửa code — không cần chuyển qua terminal riêng. Với Docker MCP, điều này có nghĩa: bạn đang sửa Dockerfile hoặc compose.yaml, hỏi ngay agent "build thử và cho tôi biết còn lỗi gì", và nhận phản hồi dựa trên container thật đang chạy, ngay trong cùng một cửa sổ.

Bài này tập trung vào cách kết nối Docker MCP với Cursor Agent Mode, workflow sửa Dockerfile/compose với phản hồi container trực tiếp, cách dùng nó để tái hiện bug chỉ xảy ra ở môi trường cụ thể, và những giới hạn/workaround bạn cần biết khi dùng Cursor cho việc này.

Kết Nối Docker MCP Với Cursor Agent Mode

Cursor đọc cấu hình MCP từ file .cursor/mcp.json ở root project, hoặc file config global trong settings của Cursor nếu bạn muốn dùng chung cho mọi project mở trong IDE.

Tạo file .cursor/mcp.json:

{
  "mcpServers": {
    "docker": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Sau khi lưu file, mở Cursor Settings → MCP, bạn sẽ thấy server docker xuất hiện với trạng thái kết nối (chấm xanh nếu thành công). Nếu không thấy, thử reload window (Cmd/Ctrl + Shift + P → "Reload Window") — Cursor không luôn tự phát hiện thay đổi file config ngay lập tức.

Để dùng Docker MCP, mở Agent Mode (chat panel với biểu tượng agent, khác với chat thường chỉ trả lời không gọi tool), và xác nhận tool Docker đã sẵn sàng bằng một prompt đơn giản:

List toàn bộ container đang chạy trong project này.

Nếu Cursor Agent trả về đúng danh sách khớp với docker ps bạn biết, kết nối đã ổn.

Kiểm soát quyền tool trong Cursor

Cursor cho phép bật/tắt approval (yêu cầu xác nhận) theo từng tool hoặc theo nhóm trong phần MCP settings. Với Docker MCP, nên bật approval bắt buộc cho các tool có side-effect (build_image, remove_container, prune, exec_in_container), và chỉ để tool đọc (list_containers, get_logs, inspect_container) chạy tự động không cần xác nhận — giúp workflow nhanh hơn cho phần đọc, vẫn an toàn cho phần ghi.

Mẹo: Ngay sau khi setup, thử một prompt có side-effect nhỏ (ví dụ "dừng container test-nginx") để xác nhận Cursor có hiện đúng dialog approval trước khi thực thi — đừng đợi tới khi bạn thao tác trên container quan trọng mới phát hiện approval chưa được cấu hình đúng.

Sửa Dockerfile Và Compose File Với Phản Hồi Container Trực Tiếp

Đây là điểm mạnh riêng biệt của Cursor so với dùng CLI thuần: bạn đang mở file Dockerfile hoặc compose.yaml trong editor, và có thể hỏi agent ngay trong context đó, tận dụng việc Cursor đã biết bạn đang nhìn vào file nào.

Workflow điển hình khi sửa Dockerfile:

Mở file Dockerfile trong editor.
Sửa một thay đổi (ví dụ đổi base image, thêm bước cài dependency mới).
Mở Agent chat, prompt: "Build lại image từ Dockerfile hiện tại đang mở, tag test build là myapp:cursor-test, cho tôi biết build có pass không và log warning nào không."
Agent gọi build_image, đọc kết quả, báo lại ngay trong chat, kèm trích dẫn dòng log liên quan nếu có lỗi.
Bạn sửa tiếp trong editor dựa trên phản hồi, lặp lại bước 3 — toàn bộ vòng lặp không cần rời khỏi Cursor.

Ví dụ prompt cụ thể hơn khi thêm một dependency mới vào Dockerfile Python:

Tôi vừa thêm "RUN pip install redis==5.0.1" vào Dockerfile đang mở.
Hãy build lại image tag "myapp:test-redis" và xác nhận:
1. Build có pass không, nếu fail trích dẫn đúng dòng lỗi.
2. Size image tăng bao nhiêu so với image "myapp:latest" hiện có
   (dùng docker images để so sánh).
3. Có warning nào về version conflict với dependency khác trong
   requirements.txt không.

Với compose.yaml, workflow tương tự nhưng ở tầng stack nhiều service. Ví dụ khi bạn sửa environment của một service:

Tôi vừa đổi biến "REDIS_URL" trong compose.yaml của service "api" từ
"redis://localhost:6379" thành "redis://cache:6379". Hãy chạy
compose_up để áp dụng thay đổi cho service "api" (không động tới
service khác), rồi kiểm tra log của "api" trong 10 giây sau khi start
để xác nhận nó kết nối redis thành công, không còn lỗi connection
refused.

Điểm cần lưu ý: yêu cầu rõ "không động tới service khác" — nhiều compose command mặc định sẽ recreate toàn bộ stack nếu không giới hạn phạm vi, có thể làm mất state của service khác đang chạy ổn định.

Dùng diff view của Cursor để review thay đổi trước khi apply

Với các thay đổi AI đề xuất trực tiếp lên Dockerfile/compose (không chỉ chạy build thử), Cursor hiện diff ngay trong editor giống như một code suggestion thông thường — bạn review từng dòng, accept hoặc reject riêng lẻ, giống hệt review một pull request nhỏ. Đây là lợi thế lớn so với CLI, nơi AI-generated content chỉ hiện dạng text trong terminal.

Mẹo: Luôn review diff Cursor hiện ra cho Dockerfile/compose giống như review code thật — đừng "Accept All" theo phản xạ. Một thay đổi nhỏ như đổi thứ tự COPY có thể vô tình phá vỡ build cache của cả team nếu bạn không để ý.

Tái Hiện Bug Đặc Thù Theo Môi Trường Bên Trong Container Từ Cursor

Bug "chỉ xảy ra ở container, không xảy ra khi chạy trực tiếp trên máy dev" là một trong những use case giá trị nhất của việc kết hợp Docker MCP với AI ngay trong IDE — vì bạn cần đối chiếu liên tục giữa code trong editor và trạng thái thực tế bên trong container.

Ví dụ tình huống: một hàm parse date hoạt động đúng khi chạy npm run dev trên máy bạn (macOS), nhưng lỗi khi chạy trong container (thường do khác timezone hoặc locale hệ thống giữa base image và máy dev).

Prompt điều tra:

Function "formatOrderDate" trong file "src/utils/date.ts" (đang mở
trong editor) trả về kết quả sai khi chạy trong container "api",
nhưng đúng khi tôi chạy trực tiếp trên máy. Hãy:
1. Exec vào container "api", chạy lệnh "date" và "node -e
   'console.log(Intl.DateTimeFormat().resolvedOptions().timeZone)'"
   để lấy timezone hiện tại của container.
2. So sánh với timezone máy tôi (tôi đang ở UTC+7).
3. Đọc lại function trong file đang mở, xác định nó có đang giả định
   timezone local của máy chạy hay không.
4. Đề xuất fix để function hoạt động nhất quán bất kể timezone của
   môi trường chạy (container hay máy dev).

Agent sẽ gọi exec_in_container để lấy timezone thật của container (thường là UTC theo mặc định của nhiều base image), đối chiếu với code trong file bạn đang mở, và chỉ ra chính xác dòng code đang dùng new Date() cộng offset cứng theo giờ địa phương thay vì dùng UTC hoặc thư viện timezone-aware (ví dụ date-fns-tz hoặc Temporal).

Các loại bug môi trường phổ biến khác cần kiểm tra tương tự

Loại khác biệt	Cách kiểm tra qua exec_in_container	Bug điển hình
Timezone	`date`, đọc biến `TZ`	Tính sai giờ, off-by-N-hours trên report/schedule
Locale	`locale`, `echo $LANG`	Format số/tiền tệ sai (dấu phẩy/chấm ngược)
Phiên bản runtime	`node -v`, `python --version`	API mới dùng được ở máy dev nhưng container dùng bản cũ hơn
File system case-sensitivity	Thử tạo file trùng tên khác hoa/thường	Import path đúng trên macOS (case-insensitive) nhưng lỗi trên container Linux (case-sensitive)
Biến môi trường thiếu	`env`, so với `.env.example`	Feature flag/API key không load, tính năng "biến mất" âm thầm

Mẹo: Với bug "chỉ lỗi trong container", luôn coi container là môi trường tham chiếu đúng (vì đó là môi trường production thật sẽ chạy), không phải máy dev — mục tiêu là sửa code để hoạt động đúng trong container, không phải "làm cho giống máy dev".

Hạn Chế Và Cách Khắc Phục Của Docker MCP Trong Cursor

Dù trải nghiệm tích hợp trong IDE rất mượt, Docker MCP trong Cursor vẫn có một số giới hạn cần biết trước.

Hạn chế	Biểu hiện thực tế	Cách khắc phục
Agent Mode đôi khi không tự động reload MCP config sau khi sửa file	Server hiện `disconnected` dù file config đã đúng	Reload window (`Cmd/Ctrl+Shift+P` → Reload Window) sau mỗi lần sửa `.cursor/mcp.json`
Log dài bị cắt trong panel chat	Log container/build dài hàng nghìn dòng hiển thị không đầy đủ trong UI chat	Yêu cầu agent lọc trước theo `tail`/từ khoá lỗi, hoặc xuất log ra file rồi mở riêng bằng editor
Approval dialog gây gián đoạn với task nhiều bước	Mỗi tool có side-effect đều dừng lại chờ xác nhận, làm chậm workflow debug nhiều bước	Với session debug đã tin tưởng, tạm nới approval cho nhóm tool read-only, giữ nguyên approval cho write/destructive
Context giữa nhiều file mở dễ gây nhầm project/service	Nếu mở nhiều compose project cùng lúc, agent có thể áp nhầm lệnh vào project khác	Luôn nêu rõ tên container/service cụ thể trong prompt, không dựa vào "file đang mở" một cách ngầm định
Không có lịch sử tool call bền lâu như terminal log	Đóng chat/reload có thể mất lịch sử các lệnh Docker đã chạy trước đó	Yêu cầu agent tóm tắt lại các thay đổi đã áp dụng vào cuối mỗi session dài, lưu riêng vào file changelog nếu cần đối chiếu sau

Một workaround hữu ích khác: với các thao tác Docker phức tạp cần chạy lặp lại nhiều lần (ví dụ full rebuild + restart cả compose stack), nên viết sẵn một script Makefile hoặc justfile gọi các lệnh Docker chuẩn, rồi để agent gọi script đó qua exec thay vì tự soạn lệnh dài mỗi lần — vừa nhất quán, vừa dễ review hơn một chuỗi tool call rời rạc.

Mẹo: Với các workflow Docker lặp lại thường xuyên (rebuild toàn bộ stack, reset database container về seed data), hãy đóng gói thành script cố định trong repo và để agent gọi script đó — an toàn hơn và dễ audit hơn nhiều so với để agent tự "sáng tạo" chuỗi lệnh mỗi lần.

Tips

Docker MCP trong Cursor phát huy giá trị lớn nhất khi bạn tận dụng đúng thế mạnh riêng của một AI-native IDE: phản hồi container gắn liền ngay với file đang sửa, và diff view giúp review thay đổi Dockerfile/compose an toàn hơn thao tác qua terminal thuần.

Luôn bật approval bắt buộc cho nhóm tool write/destructive, chỉ để tool đọc chạy tự động.
Review diff Cursor đề xuất cho Dockerfile/compose như review code thật, không "Accept All" theo phản xạ.
Với bug môi trường (timezone, locale, version), luôn dùng exec_in_container để lấy bằng chứng thật từ container, coi container là môi trường tham chiếu đúng.
Đóng gói các workflow Docker lặp lại thành script cố định (Makefile/justfile) để agent gọi lại, tránh để agent tự soạn lệnh dài mỗi lần.
Reload window sau mỗi lần sửa .cursor/mcp.json nếu server không tự cập nhật trạng thái.

Mẹo: Ghép Docker MCP với tính năng review diff sẵn có của Cursor thành quy trình chuẩn của team: mọi thay đổi Dockerfile/compose do AI đề xuất đều phải qua diff review trong Cursor trước khi commit, giống như một bước code review bắt buộc, không phải bước tuỳ chọn.