·

Confluence MCP với Claude Code CLI and VS Code

Cài đặt Confluence MCP trong Claude Code CLI and VS Code để AI agent có thể đọc và viết trang tài liệu ngay trong trình soạn thảo.

Claude Code là một trong những client hỗ trợ MCP (Model Context Protocol) toàn diện nhất hiện nay — vừa chạy được ở CLI (dòng lệnh) thuần, vừa có extension chính thức cho VS Code với UI xác nhận quyền trực quan. Bài này đi sâu vào cách cài Confluence MCP cho cả hai môi trường, cách viết prompt hiệu quả để đọc/tạo page, và một vài lệch pha (quirk) bạn sẽ gặp khi chuyển từ terminal sang IDE.

Nếu bạn chưa đọc bài "Confluence MCP Là Gì?" ở đầu module, nên đọc trước vì bài đó giải thích các tool cốt lõi (confluence_search, confluence_create_page...) và hai hướng xác thực (API token vs OAuth) — bài này sẽ không lặp lại phần nền tảng đó mà đi thẳng vào thực hành với Claude Code.

Cài Đặt Và Kết Nối Confluence MCP Vào Claude Code

Claude Code đọc cấu hình MCP server từ file .mcp.json ở root project (project-scoped), hoặc bạn có thể đăng ký global qua lệnh claude mcp add. Với Confluence, cách nhanh nhất và ít rủi ro rò rỉ secret nhất là dùng Atlassian Remote MCP (server chính thức, xác thực qua OAuth trong browser, không cần lưu API token dạng plaintext):

claude mcp add confluence --transport http --url https://mcp.atlassian.com/v1/sse

Lệnh này thêm entry vào scope local (chỉ máy bạn). Nếu muốn cả team dùng chung config, dùng flag --scope project để ghi vào .mcp.json rồi commit file đó (không chứa secret vì auth là OAuth flow, không phải token tĩnh):

claude mcp add confluence --transport http --url https://mcp.atlassian.com/v1/sse --scope project

File .mcp.json sinh ra trông như sau:

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

Lần đầu gọi tool Confluence, Claude Code sẽ mở browser để bạn login Atlassian và cấp quyền (consent screen) — sau đó token refresh tự động lưu trong keychain của hệ điều hành, bạn không cần nhập lại. Nếu công ty bạn dùng Confluence Data Center/Server on-prem (không hỗ trợ Atlassian Remote MCP), dùng server community qua API token với transport stdio:

claude mcp add confluence --scope project -- npx -y @aashari/mcp-server-atlassian-confluence

rồi set biến môi trường trong .mcp.json hoặc file .env tương ứng:

{
  "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}"
      }
    }
  }
}

Kiểm tra kết nối bằng lệnh:

claude mcp list

Nếu status hiện ✓ connected cạnh confluence, bạn đã sẵn sàng. Nếu hiện lỗi, chạy claude mcp get confluence để xem chi tiết log kết nối — lỗi phổ biến nhất là site name sai subdomain hoặc token đã bị revoke.

Mẹo: Dùng claude mcp add --scope project khi setup cho team, nhưng luôn double-check file .mcp.json trước khi commit — nếu bạn lỡ dùng server community với API token hardcode trực tiếp (không qua ${VAR}), hãy tách nó ra file .env và thêm .mcp.json chứa secret thật vào .gitignore ngay lập tức.

Đọc Và Tạo Confluence Page Ngay Từ Terminal Claude Code

Sau khi kết nối, bạn tương tác với Confluence hoàn toàn bằng ngôn ngữ tự nhiên trong REPL của Claude Code. Chạy claude để vào interactive session, rồi thử một prompt đọc trước:

Tìm trong Confluence space ENG page nào có nội dung liên quan tới
"rate limiting middleware", liệt kê title và page_id của top 5 kết quả.

Claude Code sẽ tự gọi confluence_search, và vì đây là tool read-only, theo mặc định nó chạy luôn không cần bạn confirm (trừ khi bạn đã set permission mode nghiêm hơn trong settings.json). Sau khi có page_id, bạn có thể yêu cầu đọc chi tiết:

Lấy full nội dung page có page_id 123456789, tóm tắt lại phần
"Retry Policy" thành 3 bullet point.

Để tạo page mới — đây là lúc Claude Code sẽ hiện permission prompt hỏi xác nhận trước khi gọi confluence_create_page (vì đây là write action):

Đọc source code trong src/middleware/rate-limiter.ts, viết một
Confluence page mới trong space ENG, đặt dưới parent page
"Backend Middleware Docs", tiêu đề "Rate Limiting Middleware — Design & Config",
gồm các mục: Overview, Algorithm (token bucket), Configuration Parameters,
Failure Modes, Related Services.

Bạn sẽ thấy Claude Code in ra preview nội dung page trước khi hỏi "Allow this tool call?" — đây là lúc bạn review kỹ, vì một khi confirm, page đã thật sự nằm trên Confluence và đồng nghiệp khác có thể thấy ngay. Nếu bạn chạy ở CI hoặc muốn auto-approve các tool cụ thể (chỉ nên làm với tool read-only), thêm vào settings.json:

{
  "permissions": {
    "allow": [
      "mcp__confluence__confluence_search",
      "mcp__confluence__confluence_get_page"
    ]
  }
}

Mẹo: Đừng auto-approve confluence_create_page hay confluence_update_page trong settings.json trừ khi bạn có quy trình review khác (ví dụ agent chạy trong CI với output được người review trước khi merge). Giữ human-in-the-loop cho mọi write action lên Confluence là cách rẻ nhất để tránh page rác hoặc nội dung sai lan ra cả team.

Confluence MCP Trong Claude Code VS Code Extension

Extension Claude Code cho VS Code (cài qua Extensions Marketplace, tìm "Claude Code") dùng chung cấu hình .mcp.json với bản CLI — nếu bạn đã setup ở terminal trong cùng project, mở VS Code lên nó tự nhận diện luôn, không cần cấu hình lại.

Điểm khác biệt lớn nhất là UI: thay vì prompt dạng text trong terminal, VS Code extension hiện permission request dưới dạng panel bên phải màn hình, với nút "Allow" / "Allow for this session" / "Deny" rõ ràng, kèm diff-view khi Claude sửa file code liên quan. Với Confluence MCP cụ thể, khi agent gọi confluence_create_page, panel sẽ hiện nội dung page dạng rendered markdown ngay trong sidebar — dễ review hơn nhiều so với đọc raw text trong terminal.

Một lợi ích thực tế: vì bạn đang ở trong VS Code với file code đang mở, bạn có thể ra prompt tham chiếu trực tiếp file đang active:

Dựa vào file đang mở (payment-webhook-handler.ts), tạo Confluence page
tóm tắt luồng xử lý webhook, đặt trong space ENG dưới parent
"Payment Integrations", và link ngược lại tới file này bằng đường dẫn
GitHub (nếu biết remote URL của repo).

Extension cũng hỗ trợ xem lịch sử tool call trong tab "MCP Tools" của sidebar — hữu ích khi bạn muốn audit lại agent đã gọi bao nhiêu lần confluence_update_page trong một session dài, tránh trường hợp agent update nhầm page nhiều lần do hiểu sai version number.

Mẹo: Khi làm việc với Confluence MCP trong VS Code, mở song song tab Confluence page thật trên browser (side-by-side với VS Code) trong lúc agent đang tạo/sửa page — bạn sẽ phát hiện ngay nếu format markdown chuyển sang Confluence storage format (XHTML) bị lỗi, ví dụ bảng bị vỡ layout hoặc code block mất syntax highlighting.

Prompt Mẫu Để Sinh Tài Liệu Kỹ Thuật Từ Source Code

Phần giá trị nhất của Confluence MCP không nằm ở việc đọc/viết page đơn lẻ, mà ở khả năng biến toàn bộ codebase thành nguồn sự thật (source of truth) để tự sinh tài liệu luôn khớp với code thật. Dưới đây là vài pattern prompt đã được kiểm chứng hiệu quả qua nhiều project thực tế.

Sinh tài liệu API từ router/controller:

Đọc toàn bộ file trong src/api/routes/orders/, liệt kê tất cả endpoint
(method, path, request body schema, response schema, status code).
Tạo Confluence page "Orders API Reference" trong space ENG dưới parent
"API Documentation", trình bày mỗi endpoint thành một heading H3 riêng
kèm bảng request/response.

Sinh ADR (Architecture Decision Record) từ một quyết định đã implement:

Đọc git log 20 commit gần nhất trong thư mục src/queue/, cùng với
file src/queue/README.md nếu có. Dựa vào đó, viết một ADR theo format:
Title, Status (Accepted), Context, Decision, Consequences. Tạo page
này trong space ARCH dưới parent "Architecture Decision Records".

Đồng bộ tài liệu khi refactor:

So sánh nội dung Confluence page page_id 987654321 với code hiện tại
trong src/auth/. Liệt kê những điểm page đang mô tả sai so với code
(ví dụ tên function đổi, flow đổi), sau đó update lại page cho khớp,
giữ nguyên cấu trúc heading gốc.

Một nguyên tắc chung khi viết prompt loại này: luôn chỉ định rõ (1) nguồn code cụ thể (đường dẫn thư mục/file), (2) cấu trúc heading mong muốn của page, và (3) vị trí page trong cây tài liệu (parent_id hoặc tên parent). Thiếu một trong ba, agent sẽ tự suy đoán và kết quả thường lệch với convention team bạn đang dùng.

Mẹo: Lưu các prompt template này thành snippet trong CLAUDE.md của project (mục "Confluence Doc Prompts"), để cả team dùng chung cấu trúc thay vì mỗi người viết prompt khác nhau — điều này giúp tài liệu sinh ra trên Confluence có style đồng nhất theo thời gian.

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

Vài điểm rút ra sau khi chạy Confluence MCP với Claude Code cho vài team backend/platform:

  • Terminal phù hợp cho việc chạy batch — ví dụ sinh tài liệu cho 10 service cùng lúc qua một script gọi claude -p với prompt khác nhau. VS Code extension phù hợp hơn cho workflow tương tác, review từng bước.
  • Khi agent tạo nhiều page liên tiếp trong một session dài, page sau có thể bị tạo nhầm dưới parent của page trước (do agent "nhớ" context cũ). Luôn chỉ định lại parent_id rõ ràng ở mỗi prompt tạo page mới, đừng dựa vào ngữ cảnh ngầm.
  • Nếu team dùng cả CLI và VS Code, thống nhất dùng --scope project cho .mcp.json để tránh tình trạng người dùng CLI kết nối được nhưng người dùng VS Code lại thấy "server not found" vì config chỉ nằm ở scope local của máy khác.

Mẹo: Tạo một alias hoặc script wrapper (ví dụ scripts/doc-sync.sh) gọi claude -p "<prompt cố định>" --mcp-config .mcp.json để chạy sinh tài liệu Confluence định kỳ qua cron hoặc CI job, thay vì luôn phải mở terminal gõ tay — điều này giúp tài liệu API luôn cập nhật mỗi khi có PR merge vào main.

Tiếp Confluence MCP với OpenCode