Cursor là IDE có Agent Mode (chế độ agent tự thực thi nhiều bước, gọi tool, chỉnh sửa nhiều file liên tục) built-in mạnh nhất trong nhóm AI-first editor hiện nay. Khi kết nối Notion MCP vào Cursor, bạn có thể biến một luồng làm việc vốn phải nhảy qua nhảy lại giữa browser (đọc spec) và editor (viết code) thành một luồng liền mạch: đọc spec, sinh code, rồi ghi lại implementation note — tất cả không rời khỏi IDE. Bài này tập trung vào spec-to-code workflow (luồng từ spec sang code) và các giới hạn thực tế bạn cần biết khi dùng Cursor cho việc này.
Kết Nối Notion MCP Với Cursor Agent Mode
Cursor quản lý MCP qua file .cursor/mcp.json (project-level, nên commit vào git nếu team dùng chung config, chỉ token nên tách riêng) hoặc cấu hình global trong Cursor Settings → MCP.
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ${NOTION_TOKEN}\", \"Notion-Version\": \"2022-06-28\"}"
}
}
}
}
Sau khi lưu, mở Cursor Settings → MCP Servers để xác nhận trạng thái "connected" (đèn xanh) — Cursor hiển thị UI trực quan hơn terminal-based tool, khá tiện để debug nhanh khi có lỗi kết nối.
Để dùng được tool Notion, bạn cần chuyển sang Agent Mode trong chat panel (không phải chế độ "Ask" hay "Edit" thông thường chỉ tương tác với code trong workspace) — chỉ ở Agent Mode, Cursor mới có quyền gọi tool từ MCP server bên ngoài codebase. Đây là điểm nhiều người mới dùng bị vướng: gõ prompt liên quan Notion ở chế độ "Ask" sẽ không có tác dụng vì Cursor không có quyền gọi tool ở mode đó.
Mẹo: Trong Cursor Settings → MCP, để riêng một số tool ghi (create/update page) ở trạng thái yêu cầu xác nhận thủ công (nếu Cursor version bạn dùng hỗ trợ per-tool approval), đặc biệt khi làm trên workspace Notion chung của cả team — tránh trường hợp agent tự sửa nhầm page người khác đang cần.
Đọc Spec Notion Và Scaffold Code Triển Khai
Đây là use case giá trị nhất của việc ghép Notion MCP với Cursor: bạn có spec/requirement viết trên Notion, và muốn Cursor đọc trực tiếp để sinh code scaffold (khung code khởi đầu) khớp đúng yêu cầu, thay vì bạn phải đọc rồi tự diễn giải lại bằng lời cho AI.
Ví dụ prompt trong Agent Mode:
Đọc page Notion "Feature Spec: Bulk Invoice Export" trong database "Requirements".
Dựa trên spec đó, scaffold một endpoint mới trong module src/api/invoices:
- Route POST /invoices/bulk-export
- Request body theo đúng field đã mô tả trong spec (validate bằng Zod)
- Trả về job_id để client poll trạng thái xử lý bất đồng bộ
Không cần implement logic xử lý file thật, chỉ cần scaffold đúng structure và types.
Điểm quan trọng: yêu cầu Cursor trích dẫn lại phần spec cụ thể nó đang dựa vào trước khi code, giúp bạn phát hiện sớm nếu nó hiểu sai ý spec:
Trước khi code, trích lại đúng đoạn spec mô tả field của request body,
để tôi xác nhận bạn hiểu đúng, rồi mới tiếp tục.
Cách làm hai bước này (xác nhận hiểu đúng → mới cho code) giảm đáng kể rủi ro Cursor "bịa" field hoặc logic không có trong spec gốc — một lỗi khá phổ biến khi giao thẳng task lớn mà không kiểm tra bước hiểu spec.
Mẹo: Với spec dài và phức tạp, hãy chia nhỏ: yêu cầu Cursor đọc và scaffold theo từng phần (request/response, validation, error handling) trong các lượt riêng, thay vì một prompt "làm hết toàn bộ feature". Việc chia nhỏ giúp bạn review từng phần thay vì phải audit một khối code lớn một lúc.
Đẩy Ghi Chú Triển Khai Về Lại Notion Từ Cursor
Sau khi code xong (hoặc trong lúc code), việc ghi lại các quyết định kỹ thuật, các điểm lệch so với spec ban đầu, hay câu hỏi cần product/PM xác nhận — là bước quan trọng thường bị bỏ qua vì tốn thời gian "chuyển ngữ cảnh" sang Notion. Với MCP, bạn giữ nguyên ngữ cảnh code, chỉ cần prompt:
Tôi vừa implement xong endpoint /invoices/bulk-export. So với spec ban đầu,
có 2 điểm lệch: (1) giới hạn batch tối đa 500 invoice/lần do constraint DB,
(2) dùng background job queue thay vì xử lý đồng bộ như spec mô tả ban đầu để tránh timeout.
Cập nhật page spec gốc: thêm một callout block "Implementation Notes" ở cuối page
ghi rõ 2 điểm lệch này, kèm lý do kỹ thuật.
Việc yêu cầu dùng callout block riêng (không sửa trực tiếp vào nội dung spec gốc) rất quan trọng — nó giữ nguyên vẹn spec ban đầu (cần cho việc truy vết lịch sử quyết định), đồng thời làm nổi bật rõ phần "thực tế đã lệch so với kế hoạch" cho người đọc sau này, kể cả người không tham gia buổi implement.
Một pattern khác hữu ích: tự động cập nhật property Implementation Status của page spec (nếu database Requirements có field này) ngay khi code merge — giữ Notion luôn phản ánh đúng trạng thái thực tế của dự án.
Mẹo: Luôn ghi rõ lý do kỹ thuật khi báo cáo điểm lệch, không chỉ nói "đã đổi cách làm". PM/stakeholder đọc lại page sau này cần hiểu tại sao lệch để đánh giá đúng rủi ro, không chỉ biết có lệch.
Các Hạn Chế Và Cách Xử Lý Khi Dùng Notion MCP Trong Cursor
Một số hạn chế thực tế bạn nên biết trước khi đưa workflow này vào quy trình chính thức của team:
- Agent Mode có thể "quên" ngữ cảnh Notion đã đọc nếu phiên chat quá dài và context bị cắt/tóm tắt tự động — nếu thấy Cursor code sai lệch so với spec đã đọc trước đó, hãy yêu cầu nó đọc lại page trước khi tiếp tục, đừng giả định nó vẫn "nhớ" chính xác.
- Không có cơ chế diff rõ ràng cho thay đổi trên Notion như diff code trong editor — khi Cursor sửa một page Notion, bạn không thấy được "trước/sau" trực quan như khi review code diff. Cách khắc phục thực tế: luôn yêu cầu Cursor tóm tắt lại phần đã thay đổi bằng text trong chat trước khi bạn mở Notion kiểm tra.
- Việc gọi tool Notion đôi khi làm chậm phản hồi trong Agent Mode vì phải chờ round-trip network tới Notion API, khác với việc chỉnh sửa file local gần như tức thì — với task cần nhiều lượt đọc/ghi Notion, hãy chuẩn bị tâm lý sẽ chậm hơn thao tác code thông thường.
- Table block và nested block phức tạp đôi khi bị format sai tương tự các MCP client khác — nên với bảng dữ liệu quan trọng, luôn double-check trên Notion web sau khi Cursor báo hoàn tất.
Mẹo: Tạo một checklist review ngắn (có thể lưu trong file rule của Cursor, ví dụ
.cursor/rules) để tự nhắc bản thân luôn double-check trên Notion web sau mỗi lần agent ghi dữ liệu quan trọng — đừng chỉ tin vào câu báo cáo "đã cập nhật thành công" của agent trong chat.