What Is Confluence MCP? AI Agents Meet Confluence

Nếu team bạn dùng Confluence để lưu spec, tài liệu kỹ thuật, ADR (Architecture Decision Record), runbook... thì chắc bạn đã từng gặp cảnh: spec nằm một nơi, code nằm một nơi, và sau vài sprint thì hai thứ đó lệch nhau hoàn toàn. Confluence MCP (Model Context Protocol) chính là mảnh ghép giúp AI agent — Claude Code, Cursor, Gemini CLI, OpenCode... — đọc và viết trực tiếp vào Confluence như một "cộng tác viên" thực sự, thay vì bạn phải copy-paste qua lại giữa terminal và trình duyệt.

Bài này sẽ giúp bạn hiểu Confluence MCP hoạt động ra sao, những tool nào nó cung cấp, cách xác thực an toàn, những việc AI có thể tự động hóa, và cách quản lý quyền truy cập để không biến AI agent thành lỗ hổng bảo mật của cả wiki công ty.

Core Confluence MCP Tools: Spaces, Pages Và Full-Text Search

Confluence MCP server (phổ biến nhất hiện nay là các server cộng đồng dựa trên Confluence REST API v2, hoặc server chính thức từ Atlassian Remote MCP) expose (hiển thị/cung cấp) ra cho AI agent một tập tool tương ứng với các thao tác CRUD (Create, Read, Update, Delete) trên Confluence. Về bản chất, mỗi tool call (lệnh gọi tool) là một request HTTP tới REST API của Confluence, nhưng được đóng gói lại dưới dạng function có schema rõ ràng mà LLM (Large Language Model — mô hình ngôn ngữ lớn) có thể "hiểu" và tự quyết định khi nào cần gọi.

Các tool cốt lõi mà bạn sẽ thấy trong hầu hết Confluence MCP server:

confluence_search — tìm kiếm full-text (tìm toàn văn) trên toàn bộ space hoặc theo CQL (Confluence Query Language).
confluence_get_page — lấy nội dung một page theo page_id hoặc theo title + space key.
confluence_create_page — tạo page mới, có thể chỉ định parent_id để đặt page vào đúng vị trí trong cây tài liệu.
confluence_update_page — cập nhật nội dung page hiện có (thường yêu cầu version number để tránh conflict).
confluence_list_spaces — liệt kê các space mà token đang dùng có quyền truy cập.
confluence_add_comment — thêm comment vào page, hữu ích khi AI cần "review" và để lại feedback trên tài liệu.

Ví dụ cấu hình MCP server dùng Atlassian Remote MCP (server chính thức, chạy qua OAuth) trong file cấu hình MCP chuẩn (.mcp.json hoặc tương đương tùy client):

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

Còn nếu bạn dùng một server community chạy local qua API token (phổ biến với Confluence Data Center/Server on-prem), cấu hình sẽ dạng stdio:

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

Điểm khác biệt lớn nhất so với việc bạn tự gọi REST API: AI agent tự quyết định khi nào cần search, khi nào cần đọc chi tiết một page, và tự nối các bước lại thành workflow — bạn chỉ cần ra prompt bằng ngôn ngữ tự nhiên.

Mẹo: Khi mới setup, hãy thử một prompt đơn giản kiểu "Tìm trong Confluence space ENG các page có chữ 'authentication flow'" trước khi giao việc phức tạp. Việc này giúp bạn xác nhận tool confluence_search hoạt động đúng và bạn hiểu được format kết quả trả về (thường có page_id, title, excerpt) trước khi tin tưởng agent tự động hóa các bước sâu hơn.

Xác Thực Confluence MCP: API Token Và Cấu Hình Space

Có hai hướng xác thực chính khi kết nối AI agent với Confluence, và lựa chọn đúng ngay từ đầu sẽ tránh rất nhiều đau đầu về sau.

Hướng 1: API Token cá nhân (Personal Access Token / API Token). Đây là cách phổ biến nhất với Confluence Cloud. Bạn vào id.atlassian.com → Security → API tokens → tạo token mới, sau đó dùng cặp email + token để basic-auth vào REST API. Token này gắn với danh tính cá nhân của bạn, nghĩa là AI agent sẽ có đúng những quyền mà bạn có trên Confluence — không hơn, không kém. Đây vừa là ưu điểm (dễ audit, dễ trace hành động về đúng người) vừa là nhược điểm (nếu bạn có quyền admin, agent cũng có quyền admin).

Hướng 2: OAuth 2.0 qua Atlassian Remote MCP. Atlassian cung cấp MCP server chính thức chạy remote, xác thực qua OAuth flow trong browser — không cần lưu token dạng plaintext trong file config. Cách này an toàn hơn cho môi trường team/enterprise vì token có thể revoke tập trung, có scope rõ ràng, và không lo file .mcp.json bị commit nhầm lên git kèm secret.

Với hướng API token, biến môi trường cần thiết thường là:

export CONFLUENCE_SITE_NAME="your-company"
export CONFLUENCE_USER_EMAIL="you@company.com"
export CONFLUENCE_API_TOKEN="ATATT3xFfGF0..."

Một lỗi rất hay gặp: nhầm giữa API token của Confluence và token của Jira — về mặt kỹ thuật chúng dùng chung cơ chế tạo token trên id.atlassian.com, nhưng site name/base URL khác nhau nếu bạn có nhiều product trong cùng tổ chức Atlassian. Hãy kiểm tra kỹ CONFLUENCE_SITE_NAME phải khớp đúng subdomain, ví dụ your-company trong your-company.atlassian.net.

Mẹo: Đừng bao giờ hardcode API token trực tiếp vào file .mcp.json rồi commit vào repo. Luôn dùng biến môi trường hoặc secret manager (1Password CLI, Doppler, Vault...), và thêm .mcp.json chứa secret vào .gitignore nếu client của bạn không hỗ trợ interpolate biến ${VAR} trong config.

AI Có Thể Tự Động Hóa Gì Với Confluence MCP: Pages, Comments Và Template

Đây là phần thú vị nhất — khi đã kết nối xong, những việc AI agent thực sự làm tốt trên Confluence là gì?

1. Sinh tài liệu kỹ thuật từ code. Agent đọc source code (qua filesystem tool sẵn có), tóm tắt kiến trúc, rồi gọi confluence_create_page để tạo page mới. Ví dụ prompt:

Đọc toàn bộ module payment-service/, tóm tắt luồng xử lý thanh toán,
rồi tạo một Confluence page trong space ENG, đặt dưới parent page
"Payment Service Docs", với các mục: Overview, Sequence Diagram (mô tả bằng
text), API Endpoints, Error Handling, Rollback Strategy.

2. Review và comment. Agent đọc một spec page, so sánh với code hiện tại, rồi để lại comment chỉ ra điểm chưa khớp — rất hữu ích trước khi release để đảm bảo docs không "nói dối".

3. Sinh page từ template. Nhiều team có template cố định cho ADR, RFC, postmortem. Bạn có thể yêu cầu agent lấy nội dung một page template có sẵn (confluence_get_page), rồi điền vào các phần placeholder dựa trên context hiện tại, và tạo page mới giữ đúng cấu trúc.

4. Đồng bộ hai chiều. Agent đọc spec trên Confluence để hiểu yêu cầu trước khi code, rồi sau khi code xong lại cập nhật ngược lại Confluence — mình sẽ đi sâu vào workflow này ở bài cuối module.

Mẹo: Khi yêu cầu agent tạo page, luôn chỉ định rõ parent_id hoặc tên parent page mong muốn. Nếu không, một số MCP server sẽ tạo page ở root space, khiến cây tài liệu của bạn lộn xộn rất nhanh — dọn lại thủ công tốn thời gian hơn bạn nghĩ.

Quản Lý Permission Và Bảo Mật Cho Confluence MCP Access

Đây là phần mà nhiều team bỏ qua cho tới khi xảy ra sự cố. Khi AI agent có quyền viết lên Confluence, bạn đang mở ra một actor (tác nhân) có thể tạo/sửa/xóa tài liệu ở tốc độ máy — nhanh hơn con người rất nhiều, kể cả khi nó làm sai.

Nguyên tắc least privilege (đặc quyền tối thiểu). Nếu có thể, tạo một service account riêng cho AI agent, chỉ cấp quyền vào những space thực sự cần (ví dụ chỉ space ENG, không cấp vào HR hay FINANCE), thay vì dùng token cá nhân của một senior engineer có quyền admin toàn site.

Giới hạn theo scope trong config. Với server hỗ trợ, bạn có thể giới hạn danh sách space ngay trong config:

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

Review trước khi ghi (human-in-the-loop). Với các client hỗ trợ permission prompt (Claude Code, Cursor), hãy để chế độ mặc định là hỏi xác nhận trước khi gọi các tool ghi dữ liệu (confluence_create_page, confluence_update_page, confluence_delete_page), chỉ auto-approve các tool chỉ đọc (confluence_search, confluence_get_page). Điều này giúp bạn vẫn giữ được tốc độ mà không mất kiểm soát.

Audit log. Confluence Cloud có Audit Log ở cấp admin, ghi lại mọi hành động tạo/sửa/xóa kèm actor. Nếu dùng service account riêng cho bot, bạn sẽ dễ dàng lọc ra chính xác những gì AI đã làm, tách biệt hoàn toàn với hoạt động của con người.

Mẹo: Trước khi cho AI agent quyền confluence_delete_page, tự hỏi: team bạn có thực sự cần tool này không? Phần lớn workflow chỉ cần create/update/comment. Loại bỏ hẳn quyền delete khỏi service account là cách đơn giản nhất để loại bỏ luôn rủi ro "agent xóa nhầm cả cây tài liệu" do hiểu sai prompt.

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

Một vài điều mình rút ra sau khi triển khai Confluence MCP cho vài team thực tế:

Luôn bắt đầu bằng read-only. Cho agent quyền search/read trước một tuần, quan sát log để hiểu agent gọi tool theo pattern nào, rồi mới mở quyền write.
Version conflict là chuyện thường gặp khi nhiều người (hoặc nhiều agent) cùng sửa một page. Luôn để agent đọc lại version mới nhất trước khi update, đừng cache page content quá lâu trong một session dài.
Không phải mọi thứ nên tự động hóa. Tài liệu mang tính quyết định chiến lược (roadmap, pricing) nên vẫn do người viết/review, AI chỉ nên đóng vai trò sinh tài liệu kỹ thuật thuần túy (API docs, runbook, ADR nháp).

Mẹo: Ghi lại một file CONFLUENCE_CONVENTIONS.md trong repo, mô tả rõ cấu trúc space, parent page mặc định cho từng loại tài liệu, và style guide. Đưa file này vào context (qua CLAUDE.md, AGENTS.md hay tương đương) để mọi agent — bất kể bạn dùng Claude Code, Cursor hay Gemini CLI — đều tuân theo cùng một convention khi tạo tài liệu trên Confluence.