Confluence MCP Setup: Cursor | AgenticSkillset.org

Cursor là IDE (dựa trên VS Code fork) với Agent Mode mạnh, được nhiều team frontend/fullstack chọn làm công cụ chính vì tích hợp sâu vào luồng viết code — không cần chuyển qua terminal riêng như CLI agent. Bài này hướng dẫn cách nối Confluence MCP vào Cursor, viết prompt để đọc spec và sinh code, rồi đẩy tài liệu tự sinh ngược lại Confluence, cùng những edge case bạn nên biết trước.

Bài giả định bạn đã nắm phần tổng quan Confluence MCP (tool cốt lõi, hai hướng xác thực) ở bài đầu module — ở đây tập trung thẳng vào phần đặc thù của Cursor.

Kết Nối Confluence MCP Vào Cursor Agent Mode

Cursor đọc cấu hình MCP từ file .cursor/mcp.json trong project (project-scoped) hoặc ~/.cursor/mcp.json cho cấu hình global. Với Atlassian Remote MCP:

{
  "mcpServers": {
    "confluence": {
      "url": "https://mcp.atlassian.com/v1/sse"
    }
  }
}

Sau khi lưu file, mở Cursor Settings → Features → MCP, bạn sẽ thấy confluence xuất hiện trong danh sách với nút "Needs login" — click vào để mở OAuth flow trong browser. Sau khi authorize, trạng thái chuyển thành dấu tích xanh kèm số lượng tool đã load (thường 6-10 tool tùy version server).

Với server community qua API token (Confluence Data Center on-prem):

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "CONFLUENCE_SITE_NAME": "your-company",
        "CONFLUENCE_USER_EMAIL": "you@company.com",
        "CONFLUENCE_API_TOKEN": "${CONFLUENCE_API_TOKEN}"
      }
    }
  }
}

Để dùng Confluence MCP, bạn phải bật Agent Mode (không phải Ask mode hay Edit mode) — chọn ở dropdown trên cùng khung chat, hoặc gõ Cmd/Ctrl + I để mở Agent panel trực tiếp. Chỉ ở Agent Mode, Cursor mới cho phép model tự quyết định gọi tool MCP; ở Ask mode, MCP tool bị disable hoàn toàn vì mode này chỉ dùng để hỏi đáp không thực thi hành động.

Kiểm tra nhanh bằng prompt trong Agent panel:

Kiểm tra kết nối Confluence bằng cách search space ENG với từ khóa
"test", báo lại số lượng kết quả tìm được.

Nếu Cursor phản hồi mà không thấy icon tool-call xuất hiện trong chat, khả năng cao Agent Mode chưa được chọn hoặc server MCP chưa load — quay lại Settings → MCP kiểm tra lại trạng thái kết nối.

Mẹo: Sau khi authorize OAuth lần đầu, restart Cursor một lần để đảm bảo token được cache đúng vào keychain — một vài phiên bản Cursor có bug nhẹ khiến session OAuth không persist qua lần mở lại app nếu bạn không restart sau khi authorize lần đầu.

Đọc Spec Trên Confluence Và Sinh Boilerplate Code Trong Cursor

Điểm mạnh riêng của Cursor so với CLI agent: nó đang chạy ngay trong IDE với toàn bộ project structure sẵn có trong context, nên việc "đọc spec rồi sinh code khớp với convention hiện tại của project" mượt hơn nhiều. Thử prompt:

Đọc Confluence page trong space PROD, title "Webhook Retry Policy — Spec",
sau đó tạo file src/services/webhook/retry-policy.ts implement đúng
logic retry được mô tả (exponential backoff, max retries, dead-letter
queue), theo đúng code style và pattern đang dùng trong
src/services/webhook/handler.ts.

Cursor sẽ gọi confluence_search → confluence_get_page để lấy spec, rồi dùng codebase context (đọc file handler.ts để học convention) trước khi sinh code mới. Đây là combo mạnh nhất của Confluence MCP trong IDE: spec làm nguồn yêu cầu, code hiện tại làm nguồn convention — kết quả sinh ra thường khớp style project hơn so với chỉ đưa spec text thuần cho model không có context codebase.

Với spec phức tạp có nhiều phần, nên tách nhỏ để tránh agent bỏ sót:

Đọc Confluence page "Webhook Retry Policy — Spec" trong space PROD.
Trước khi code, liệt kê lại từng requirement dưới dạng checklist đánh số.
Sau khi tôi confirm checklist đúng, mới bắt đầu implement.

Cách làm hai bước này (liệt kê checklist → confirm → code) giúp bạn bắt lỗi hiểu sai spec ngay từ đầu, trước khi agent viết cả trăm dòng code dựa trên một yêu cầu bị hiểu nhầm.

Mẹo: Với spec dài hoặc quan trọng, luôn yêu cầu Cursor liệt kê lại requirement thành checklist trước khi code — chi phí thêm một round trip nhỏ này rẻ hơn rất nhiều so với việc phải review lại cả file code sinh sai từ một spec bị hiểu lầm.

Đẩy Tài Liệu Tự Sinh Ngược Lại Confluence Qua Cursor

Sau khi code xong (dù do agent viết hay bạn viết tay), bước tiếp theo trong vòng lặp là cập nhật lại tài liệu trên Confluence để phản ánh đúng những gì đã implement — đừng để spec đứng yên khi code đã tiến xa hơn.

Đọc file src/services/webhook/retry-policy.ts vừa tạo. Cập nhật lại
Confluence page "Webhook Retry Policy — Spec" (page_id lấy từ lần
search trước), thêm một mục mới "Implementation Notes" ở cuối page,
mô tả: (1) các tham số cấu hình thực tế trong code (giá trị default),
(2) những điểm implementation khác với spec ban đầu, (3) đường dẫn
tới file code tương ứng trên GitHub.

Chú ý: confluence_update_page thường yêu cầu bạn cung cấp đúng version number hiện tại của page để tránh conflict — nếu người khác vừa sửa page này trong lúc bạn code, agent cần đọc lại page (gọi confluence_get_page) để lấy version mới nhất trước khi update, không nên dùng version đã lấy từ đầu session vì có thể đã lỗi thời.

Một use case khác rất thực tế: cập nhật changelog page mỗi khi release.

Đọc CHANGELOG.md trong root repo, lấy phần mục mới nhất (version chưa
được sync). Thêm một section mới vào đầu Confluence page "Release Notes"
trong space PROD với đúng nội dung đó, giữ định dạng: heading là version
number, bullet list là các thay đổi, chia theo Added/Changed/Fixed.

Mẹo: Trước khi để Cursor update một page quan trọng (spec đang được nhiều người theo dõi), yêu cầu nó show diff dạng text trước ("liệt kê phần sẽ thêm/sửa trước khi thực thi update") thay vì update thẳng — điều này giúp bạn review nhanh trong chat panel mà không cần mở page thật trên browser mỗi lần.

Hạn Chế Đã Biết Và Các Edge Case

Vài điểm cần lưu ý khi dùng Confluence MCP trong Cursor, dựa trên kinh nghiệm triển khai thực tế:

Agent Mode đôi khi "quên" gọi tool MCP nếu prompt không đủ rõ ràng. Nếu bạn chỉ nói "cập nhật Confluence đi" mà không nêu rõ page nào, Cursor có xu hướng hỏi lại hoặc — tệ hơn — tự bịa một page mới thay vì tìm page đã có. Luôn nêu rõ tên page hoặc page_id cụ thể trong prompt.

Giới hạn số tool call trong một lượt agent (tool call budget). Với các workflow phức tạp (search → get 3 page → so sánh → tạo page mới → thêm comment), Cursor có thể dừng giữa chừng nếu vượt quá giới hạn tool call cho phép trong một turn, tùy theo cấu hình model. Khi gặp tình huống này, chia prompt thành nhiều bước nhỏ hơn thay vì gộp một prompt siêu dài.

Xung đột giữa nhiều MCP server cùng tên tool. Nếu bạn có cả Confluence MCP và Jira MCP cùng cấu hình (cả hai đều từ Atlassian, dễ có tool trùng tiền tố atlassian_), Cursor có thể gọi nhầm server khi tên tool không đủ khác biệt. Đặt tên server rõ ràng trong mcp.json (confluence và jira riêng biệt, không dùng chung tên atlassian) để tránh nhầm lẫn.

Rendering bảng phức tạp khi convert markdown sang storage format. Giống các client khác, bảng có merge cell hoặc nested list trong markdown có thể bị Confluence storage format render sai layout — luôn kiểm tra lại page thật sau khi tạo/update có chứa bảng phức tạp.

Mẹo: Với workflow nhiều bước (đọc nhiều page, so sánh, rồi tạo/update), chia thành 2-3 prompt tuần tự thay vì một prompt dài duy nhất — vừa tránh vượt tool call budget, vừa cho bạn điểm dừng để review kết quả trung gian trước khi agent tiếp tục.

Mẹo Và Lưu Ý Thực Chiến

Kinh nghiệm rút ra khi triển khai Confluence MCP với Cursor cho vài team frontend/fullstack:

Agent Mode + Confluence MCP mạnh nhất khi dùng cho vòng lặp "đọc spec → code → update lại spec" trong cùng một phiên làm việc, vì Cursor giữ context code liên tục — tránh phải copy-paste giữa nhiều tool riêng biệt.
Với team lớn, cân nhắc quy định rõ trong .cursor/rules (hoặc AGENTS.md) về việc agent chỉ được confluence_update_page trên page thuộc space cụ thể (ví dụ chỉ ENG, không đụng HR/LEGAL) — nhắc lại rule này trong context giúp giảm rủi ro agent update nhầm page ngoài phạm vi.
Định kỳ (ví dụ hàng tháng) rà lại danh sách page do AI tạo/update qua Confluence Audit Log, đối chiếu với service account/email dùng cho Cursor, để phát hiện sớm nếu có page bị tạo lệch convention mà không ai để ý.

Mẹo: Thêm một dòng chuẩn trong .cursor/rules/confluence.md: "Mọi page Confluence do agent tạo phải có parent_id rõ ràng và không được đặt ở root space; luôn confirm với user tên page và vị trí trước khi gọi confluence_create_page." — quy tắc nhỏ này giúp Cursor tự giác tuân theo convention team ngay từ system-level context, giảm nhu cầu nhắc lại mỗi lần prompt.