OpenCode là một agentic coding tool mã nguồn mở, cho phép bạn tự chọn model backend (Claude, GPT, các model open-weight qua Ollama/OpenRouter...) và có hệ thống cấu hình MCP khá linh hoạt qua file opencode.json. Vì OpenCode hướng tới việc chạy trong terminal với triết lý "mang lại quyền kiểm soát cho engineer", cách nó xử lý Notion MCP có một số khác biệt đáng chú ý so với Claude Code — đặc biệt là ở cách quản lý permission cho tool gọi write. Bài này tập trung vào việc cấu hình đúng, và một use case rất thực tế: biến biên bản họp thành trang requirement có cấu trúc.
Cài Đặt Và Kết Nối Notion MCP Với OpenCode
OpenCode đọc cấu hình MCP từ file opencode.json (đặt ở root project hoặc global config ~/.config/opencode/opencode.json). Cấu hình Notion MCP điển hình:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"notionApi": {
"type": "local",
"command": ["npx", "-y", "@notionhq/notion-mcp-server"],
"environment": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer {env:NOTION_TOKEN}\", \"Notion-Version\": \"2022-06-28\"}"
},
"enabled": true
}
}
}
Khác với Claude Code, OpenCode dùng key mcp (không phải mcpServers) và field type: "local" để chỉ rõ đây là MCP server chạy dạng process con qua stdio, phân biệt với MCP server dạng "remote" (kết nối qua URL/SSE). Đặt NOTION_TOKEN trong biến môi trường shell hoặc file .env được OpenCode tự load, tránh hardcode token vào file config commit lên git.
Sau khi cấu hình, khởi động OpenCode và gõ lệnh kiểm tra:
/mcp
Lệnh này (tuỳ phiên bản OpenCode có thể là menu tương tác) liệt kê các MCP server đã đăng ký và trạng thái kết nối. Nếu server hiện failed, gần như luôn là do package @notionhq/notion-mcp-server chưa cài được (thử chạy thẳng npx -y @notionhq/notion-mcp-server ngoài terminal để xem lỗi gốc) hoặc token sai định dạng.
Mẹo: OpenCode cho phép bật/tắt từng MCP server theo từng project riêng biệt bằng field
enabled. Với các project không liên quan tới Notion, hãy tắt server này để giảm số lượng tool được nạp vào context — quá nhiều tool cùng lúc làm agent dễ chọn sai tool hơn (một vấn đề thực tế gọi là "tool selection accuracy" giảm khi tool count tăng).
Đọc Page Và Viết Nội Dung Có Cấu Trúc Từ OpenCode
Vì OpenCode cho engineer kiểm soát permission ở mức chi tiết (bạn có thể set tool nào cần approve trước khi chạy trong file cấu hình, qua field permission), workflow đọc/viết Notion ở đây có một bước "duyệt" rõ ràng hơn Claude Code mặc định.
Ví dụ cấu hình permission chỉ cho phép đọc tự do, còn ghi thì phải hỏi trước:
{
"permission": {
"tool": {
"notionApi_search": "allow",
"notionApi_retrieve-a-page": "allow",
"notionApi_create-a-page": "ask",
"notionApi_update-a-page": "ask"
}
}
}
Tên tool cụ thể có thể khác đôi chút tuỳ version package MCP, bạn nên chạy /mcp hoặc xem log để lấy tên chính xác trước khi cấu hình permission.
Với cấu hình trên, khi bạn prompt:
Đọc page "API Design Guidelines" trong Notion, sau đó viết một page mới
"Payment API - Design Review" áp dụng đúng các nguyên tắc trong guideline đó
cho API thanh toán tôi đang thiết kế (đính kèm bên dưới).
OpenCode sẽ tự chạy bước đọc (đã allow), nhưng dừng lại xin xác nhận trước khi tạo page mới — đúng với tinh thần "human-in-the-loop" cho hành động ghi dữ liệu. Đây là điểm khác biệt lớn so với việc để agent tự chạy toàn bộ không cần confirm.
Mẹo: Luôn set các tool "ask" cho toàn bộ nhóm ghi dữ liệu (create/update/append) trong giai đoạn đầu làm quen với Notion MCP. Sau khi đã tin tưởng prompt pattern của mình (thường sau 1-2 tuần), bạn có thể chuyển một số tool ít rủi ro sang "allow" để tăng tốc độ làm việc.
Ví Dụ Thực Tế: Biến Biên Bản Họp Thành Trang Requirement
Đây là một trong những use case tiết kiệm thời gian rõ rệt nhất cho engineer/lead vừa họp xong và cần chốt requirement ngay. Giả sử bạn có transcript họp (từ tool ghi âm-transcribe hoặc note tay), quy trình thực tế:
Bước 1 — Dán transcript vào OpenCode và yêu cầu trích xuất decision:
Dưới đây là transcript cuộc họp về feature "Bulk export orders" (dán nội dung).
Trích ra: (1) các quyết định đã chốt, (2) các câu hỏi còn mở chưa có câu trả lời,
(3) action item kèm người phụ trách nếu có nhắc tên.
Bước 2 — Yêu cầu tạo page Notion theo cấu trúc requirement chuẩn của team:
Từ nội dung vừa trích xuất, tạo page mới trong database "Requirements"
với title "Bulk Export Orders - Requirement", gồm các section:
Context, Decisions, Open Questions, Action Items (dạng checklist có gắn assignee nếu biết).
Trước khi tạo, cho tôi xem outline để duyệt.
Bước 3 — Sau khi outline được duyệt, xác nhận cho OpenCode ghi vào Notion, và kiểm tra lại page vừa tạo — đặc biệt phần checklist, vì Notion checklist là block to_do riêng, cần agent map đúng thay vì chỉ là bullet text có dấu [ ].
Cách làm này giúp biên bản họp — thứ thường bị "chìm" trong một file note rời rạc — trở thành tài liệu requirement có cấu trúc, tra cứu được, và liên kết được với database khác trong Notion.
Mẹo: Luôn yêu cầu agent giữ nguyên văn các câu hỏi mở (Open Questions) thay vì tự suy diễn câu trả lời. AI có xu hướng "lấp đầy khoảng trống" bằng suy luận hợp lý nhưng không có cơ sở thực — với requirement, một câu hỏi mở bị AI tự trả lời sai còn nguy hiểm hơn việc để trống.
Các Hạn Chế Đã Biết Của Notion MCP Trong OpenCode
Sau một thời gian dùng thực chiến, có vài hạn chế bạn nên biết trước để không mất thời gian debug nhầm hướng:
- Độ chính xác mapping block đôi khi không hoàn hảo với nội dung phức tạp (nested toggle, database inline trong page) — nếu kết quả không như mong đợi, thử yêu cầu agent chia nhỏ task thành từng block một thay vì tạo cả page phức tạp trong một lần gọi.
- Model open-weight nhỏ (chạy qua Ollama) thường yếu hơn Claude/GPT trong việc chọn đúng tool khi có nhiều tool Notion cùng lúc — nếu bạn đang dùng model nhỏ để tiết kiệm chi phí, nên giảm số tool bật cùng lúc hoặc dùng model lớn hơn riêng cho task liên quan Notion.
- Rate limit của Notion API (khoảng 3 request/giây theo mặc định cho integration thông thường) có thể khiến các task xử lý nhiều page bị chậm hoặc lỗi tạm thời — OpenCode không tự động retry theo backoff một cách nhất quán ở mọi phiên bản, nên với batch job lớn, hãy chia nhỏ thành nhiều lần chạy.
- Không có UI trực quan xem trước block như Notion web — mọi review đều qua text log, nên với page phức tạp, tốt nhất vẫn là mở Notion web để xem lại bằng mắt sau khi agent hoàn tất.
Mẹo: Khi cần xử lý batch nhiều page (ví dụ cập nhật status cho 50 task cùng lúc), hãy chia thành các đợt nhỏ (10-15 page/lần) và yêu cầu agent báo cáo kết quả từng đợt. Việc này giúp bạn phát hiện sớm nếu có page bị lỗi do rate limit, thay vì phát hiện sau khi đã "âm thầm" bỏ sót nhiều page cuối batch.