·

Notion MCP Là Gì?

Tìm hiểu Notion MCP là gì và cách nó giúp AI agent đọc và viết trang, database.

Nếu team bạn đang dùng Notion làm nơi lưu spec, database task, tài liệu kỹ thuật hay wiki nội bộ, thì Notion MCP (Model Context Protocol) chính là cầu nối giúp AI agent — Claude Code, Cursor, Gemini CLI, OpenCode... — đọc và ghi trực tiếp vào Notion như một cộng sự thực sự, thay vì bạn phải copy-paste nội dung qua lại. Đây không phải một tính năng "cho vui" — với engineer làm việc theo mô hình spec-driven development, đây là mảnh ghép giúp AI agent hiểu đúng requirement, cập nhật đúng database, và giữ tài liệu luôn đồng bộ với code. Bài này sẽ đi từ việc Notion MCP cung cấp tool gì, cách xác thực, đến giới hạn thực tế khi AI chỉnh sửa nội dung Notion — để bạn setup đúng ngay từ đầu và tránh những cái bẫy thường gặp.

Các Tool Cốt Lõi Của Notion MCP: Page, Database, Block Và Search

Notion MCP server (gói chính thức từ Notion, thường được cài qua npx -y @notionhq/notion-mcp-server) expose một tập tool (công cụ) cho AI agent gọi thông qua tool calling (gọi công cụ) — về bản chất đây là lớp bọc quanh Notion REST API, nhưng được chuẩn hoá theo giao thức MCP để bất kỳ client hỗ trợ MCP nào cũng gọi được theo cùng một cách.

Các nhóm tool quan trọng nhất bạn sẽ dùng hàng ngày:

  • Search — tìm page/database theo từ khoá, tương đương thanh tìm kiếm trong Notion nhưng agent gọi được bằng code. Đây thường là bước đầu tiên trong mọi workflow, vì agent cần tìm đúng page_id hoặc database_id trước khi đọc/ghi.
  • Retrieve page / retrieve block children — đọc nội dung một page, bao gồm toàn bộ cây block bên trong.
  • Create page / update page properties — tạo page mới trong một database hoặc dưới một page cha, cập nhật property (trạng thái, ngày, người phụ trách...).
  • Append block children / update block — chèn thêm nội dung (đoạn văn, heading, bảng, code block...) vào giữa hoặc cuối một page.
  • Query database — lọc, sort các record trong database theo filter (tương tự việc bạn filter view trong Notion UI).

Ví dụ prompt thực tế bạn có thể gõ cho agent sau khi đã kết nối MCP:

Tìm database "Product Backlog" trong Notion, lọc các item có status = "In Review",
rồi tóm tắt lại thành 5 dòng cho tôi, kèm link tới từng page.

Agent sẽ tự chọn tool search để tìm database, sau đó gọi query database với filter tương ứng — bạn không cần biết tên tool chính xác, chỉ cần diễn đạt rõ ý định.

Mẹo: Khi mới làm quen, hãy yêu cầu agent "list ra các tool Notion MCP mà bạn đang có quyền dùng" trước khi giao việc phức tạp. Điều này giúp bạn biết chính xác agent có thể tự động hoá tới đâu, tránh kỳ vọng sai (ví dụ tưởng agent có thể xoá database nhưng thực ra server không expose tool đó).

Xác Thực Notion MCP: Integration Token Và Quyền Chia Sẻ Page

Notion MCP không tự nhiên có quyền truy cập vào workspace của bạn — nó hoạt động thông qua một internal integration (tích hợp nội bộ) mà bạn tạo tại trang quản trị https://www.notion.so/profile/integrations. Sau khi tạo, Notion cấp cho bạn một integration token dạng ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (token cũ hơn có thể có prefix secret_).

Cấu hình MCP server điển hình (ví dụ cho Claude Code, đặt trong file config MCP dạng JSON):

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_xxx\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}

Lưu ý: tên biến môi trường và cách cấu hình có thể thay đổi theo từng phiên bản package, nên luôn kiểm tra lại README chính thức của @notionhq/notion-mcp-server trước khi copy nguyên văn.

Điểm dễ gây bối rối nhất với người mới: có token không có nghĩa là agent thấy được toàn bộ workspace. Notion dùng mô hình permission theo kiểu "share thủ công" — bạn phải vào từng page hoặc database, bấm Share → Connections, rồi thêm chính integration đó vào. Nếu agent báo "page not found" hoặc "insufficient permissions" dù bạn chắc chắn page đó tồn tại, 90% nguyên nhân là do quên share.

Với workspace lớn, cách làm thực tế nhất là: share ở cấp page cha cao nhất có thể (ví dụ share cả page "Engineering Wiki"), vì quyền truy cập sẽ tự động lan xuống toàn bộ page con — tránh việc phải share tay từng page lẻ.

Mẹo: Tạo riêng một integration cho mỗi mục đích (một cho "AI đọc tài liệu", một cho "AI cập nhật task tracker") thay vì dùng chung một token full-quyền cho mọi agent. Cách này giúp bạn dễ audit và revoke quyền khi cần, đúng nguyên tắc least privilege (đặc quyền tối thiểu).

AI Có Thể Tự Động Hoá Gì: Sinh Doc, Cập Nhật Database Và Tóm Tắt

Sau khi kết nối xong, câu hỏi thực tế là: agent giúp được gì trong công việc hàng ngày của một senior engineer? Dưới đây là các nhóm use case đã được kiểm chứng hiệu quả:

1. Sinh tài liệu kỹ thuật từ code. Bạn có thể trỏ agent vào một module code, yêu cầu nó đọc, rồi viết một page Notion mô tả kiến trúc, luồng dữ liệu, các edge case đã xử lý. Ví dụ prompt:

Đọc source code trong thư mục src/payment-service, sau đó tạo một page mới
trong database "Technical Docs" với tiêu đề "Payment Service Architecture",
bao gồm sơ đồ luồng request bằng text, danh sách API endpoint, và các case lỗi đã handle.

2. Cập nhật database theo trạng thái công việc. Agent có thể tự set property Status từ "To Do" sang "In Progress" hoặc "Done" khi bạn báo đã hoàn thành một task, giúp tracker luôn phản ánh đúng thực tế mà không tốn thời gian click chuột.

3. Tóm tắt và tổng hợp thông tin rải rác. Đây là use case AI thể hiện rõ giá trị nhất — tổng hợp nhiều page rời rạc (meeting note, spec cũ, comment) thành một bản requirement gọn gàng.

4. Sinh release notes / changelog từ commit log hoặc PR description, rồi publish thẳng vào page "Release Notes" trên Notion.

Điều cần nhấn mạnh: agent làm tốt nhất khi task có phạm vi rõ ràng và có thể kiểm tra lại được (bạn đọc lại kết quả trước khi tin tưởng hoàn toàn), không nên giao việc "tự quản lý cả roadmap" mà không có review.

Mẹo: Luôn yêu cầu agent trích link tới page/record đã sửa trong câu trả lời cuối. Việc này giúp bạn review nhanh mà không phải tự đi tìm agent vừa đổi gì ở đâu trong workspace.

Hiểu Block Model Của Notion Và Ảnh Hưởng Đến Việc AI Chỉnh Sửa

Đây là phần kỹ thuật quan trọng nhất mà nhiều người bỏ qua, dẫn đến việc AI "sửa hỏng" format Notion. Notion không lưu nội dung dạng một chuỗi Markdown đơn giản — mọi thứ trong page (đoạn văn, heading, bullet, table, callout, code block...) là một block, và mỗi block có type riêng, có thể chứa children (block con) tạo thành cấu trúc cây (tree), không phải danh sách phẳng (flat list).

Điều này có ba hệ quả trực tiếp khi làm việc với AI agent:

  1. Append khác với replace. Khi bạn nói "cập nhật page X", agent thường có xu hướng append (thêm) block mới vào cuối page thay vì sửa block cũ, vì API update block yêu cầu biết chính xác block_id cần sửa — điều mà agent phải đọc trước (retrieve block children) rồi mới xác định được. Nếu bạn không nói rõ, agent có thể tạo ra page bị lặp nội dung.
  2. Table trong Notion là block đặc biệt (table block chứa các table_row con), không giống Markdown table thông thường — nên khi agent sinh nội dung có bảng, kết quả đôi khi không như kỳ vọng nếu server MCP xử lý chuyển đổi Markdown → block chưa hoàn hảo.
  3. Giới hạn độ sâu và số lượng block trong một request. Notion API giới hạn số block append trong một lần gọi (thường quanh mốc 100 block/request), nên với page dài, agent cần chia nhiều lần gọi — đây là lý do tạo page rất dài qua MCP có thể chậm hoặc bị cắt giữa đường.

Cách xử lý thực tế: khi giao task "cập nhật" (không phải "tạo mới"), hãy yêu cầu agent đọc lại toàn bộ page hiện tại trước, xác nhận với bạn phần nào sẽ sửa, rồi mới thực hiện — tránh tình trạng nội dung cũ và mới trộn lẫn lộn xộn.

Mẹo: Với page quan trọng (spec chính, tài liệu compliance), luôn yêu cầu agent trả lời dạng "dry-run": mô tả nó sẽ sửa gì trước khi thực sự gọi tool ghi dữ liệu. Nhiều AI agent hỗ trợ chế độ xác nhận trước khi thực thi tool ghi (write) — hãy tận dụng chế độ này cho các page rủi ro cao.

Mẹo Hay Khi Bắt Đầu Với Notion MCP

Trước khi chuyển sang các bài hướng dẫn cấu hình chi tiết cho từng công cụ (Claude Code, Cursor, Gemini CLI, OpenCode), hãy chốt lại vài nguyên tắc nền tảng để tránh mất thời gian debug không cần thiết.

  • Luôn kiểm tra quyền share trước khi báo lỗi "không tìm thấy page" — đây là nguyên nhân số một.
  • Bắt đầu với một sandbox page/database riêng để agent "tập luyện" trước khi cho chạy trên workspace thật.
  • Ghi rõ trong prompt bạn muốn agent tạo mới, cập nhật tại chỗ, hay chỉ đọc — đừng để agent tự đoán ý định.
  • Theo dõi version của Notion API (Notion-Version header) vì Notion có release breaking change theo từng version cụ thể, không tự động áp dụng cho integration cũ.

Mẹo: Lưu lại một file "runbook" ngắn (có thể chính là một page Notion) ghi lại các prompt mẫu đã hoạt động tốt với team bạn — coi đây như một bộ "playbook" prompt để người mới trong team không phải dò lại từ đầu.

Tiếp Notion MCP với Claude Code CLI and VS Code