·

Airtable MCP với OpenCode

Cài đặt Airtable MCP trong OpenCode để AI agent có thể đọc và cập nhật base và record ngay trong trình soạn thảo.

OpenCode là coding agent mã nguồn mở, terminal-first, hỗ trợ MCP server qua file cấu hình opencode.json, tương tự cách Claude Code hay Cursor làm nhưng với một vài khác biệt về cú pháp và hành vi mà bạn cần biết trước khi cắm Airtable vào. Bài này hướng dẫn cài đặt Airtable MCP cho OpenCode, cách đọc table/ghi record trực tiếp từ agent, một ví dụ thực tế xây feature matrix từ dữ liệu requirement, và các hạn chế hiện tại của Airtable MCP khi chạy trong OpenCode mà bạn nên biết để tránh mất thời gian debug sai chỗ.

Cài Đặt Và Kết Nối Airtable MCP Vào OpenCode

OpenCode đọc cấu hình MCP từ file opencode.json ở project root (hoặc ~/.config/opencode/opencode.json cho cấu hình toàn cục). Cấu trúc khai báo MCP server local (chạy qua stdio) như sau:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "airtable": {
      "type": "local",
      "command": ["npx", "-y", "airtable-mcp-server"],
      "environment": {
        "AIRTABLE_API_KEY": "patXXXXXXXXXXXXXX.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      "enabled": true
    }
  }
}

Lưu ý khác biệt so với các client khác: OpenCode dùng key mcp (không phải mcpServers), type: "local" để khai báo server chạy qua stdio (có type: "remote" cho server HTTP/SSE nếu Airtable từng expose endpoint như vậy), và field environment (không phải env). Nếu bạn copy nguyên cấu hình từ Claude Code/Cursor sang mà không đổi tên field, OpenCode sẽ báo lỗi parse config hoặc im lặng bỏ qua server — nên luôn kiểm tra đúng schema trước.

Sau khi lưu file, khởi động lại OpenCode session hoặc chạy lệnh reload nếu có, rồi kiểm tra server đã lên chưa:

opencode
/mcp

Lệnh /mcp liệt kê các server đã kết nối kèm trạng thái — nếu airtable hiện error, thường do sai đường dẫn npx, thiếu Node.js trong PATH của môi trường chạy OpenCode, hoặc token PAT không hợp lệ/hết quyền.

Thử một câu lệnh xác minh:

List all bases available through the airtable MCP server.

Mẹo: Khi OpenCode chạy trong container/CI không có Node.js cài sẵn, dùng bunx -y airtable-mcp-server thay cho npx nếu image của bạn có Bun nhưng không có Node đầy đủ — tốc độ khởi động server cũng nhanh hơn đáng kể so với npx cold-start.

Đọc Table Và Ghi Record Trực Tiếp Từ OpenCode

Sau khi kết nối ổn, OpenCode agent có thể đọc schema và dữ liệu giống các client khác, nhưng cách bạn diễn đạt task ảnh hưởng nhiều đến việc agent chọn đúng tool.

Đọc schema trước khi làm bất kỳ việc gì:

Mô tả schema của table "Requirements" trong base "Product Roadmap":
liệt kê từng field, type, và option (nếu là single/multi select).

Bước này quan trọng vì OpenCode (cũng như hầu hết agent khác) không tự "nhớ" schema giữa các phiên làm việc khác nhau — mỗi session mới nên bắt đầu bằng bước mô tả schema nếu bạn định giao việc ghi dữ liệu, tránh agent đoán sai field name hoặc option value.

Đọc record theo điều kiện:

Trong table "Requirements", tìm các record có Status = "Blocked".
Hiển thị Title, Blocked Reason, Assignee.

Ghi record mới:

Tạo record mới trong table "Requirements":
Title = "Add rate limiting to public API",
Status = "New",
Priority = "Medium",
Description = "Ngăn abuse từ client gọi API không giới hạn,
cần thêm middleware rate limit ở gateway."

Cập nhật record đã có, match theo điều kiện chứ không theo recordId cụ thể (khi bạn chưa biết recordId):

Tìm record có Title chứa "rate limiting" trong table "Requirements",
cập nhật Status = "In Progress", Assignee = "Minh Tran".

Với OpenCode, nên luôn yêu cầu agent xác nhận lại record vừa match được (in ra Title + recordId) trước khi update, vì OpenCode có thể chọn thực thi tool call nhanh hơn (ít hỏi lại xác nhận) so với một số client có UI approval mặc định chặt hơn.

Mẹo: Thêm rule vào file AGENTS.md/context project của bạn: "Trước khi update hoặc delete record Airtable, luôn liệt kê record match được và chờ xác nhận" — OpenCode đọc các file context này ở đầu session và sẽ tuân theo như một chỉ dẫn hệ thống lâu dài, không cần lặp lại mỗi lần prompt.

Ví Dụ Thực Tế: Xây Feature Matrix Từ Product Requirement

Một bài toán rất thực tế: bạn có bảng Requirements chứa nhiều record rời rạc, và cần tổng hợp thành một feature matrix — bảng so sánh feature theo platform/tier, dùng để review với stakeholder hoặc đưa vào tài liệu sales.

Giả sử schema table Requirements có các field: Title, Feature Area (single select: Auth, Billing, Reporting...), Platform (multi select: Web, iOS, Android), Tier (single select: Free, Pro, Enterprise), Status.

Prompt xây feature matrix:

Đọc toàn bộ record trong table "Requirements" của base "Product Roadmap"
có Status = "Done".
Tổng hợp thành một feature matrix dạng Markdown table:
- Dòng: từng Feature Area
- Cột: Free, Pro, Enterprise
- Giá trị: danh sách Title thuộc feature area đó, chỉ hiện ở cột Tier
  tương ứng; nếu một feature có ở nhiều Platform, ghi chú platform
  trong ngoặc, ví dụ "SSO Login (Web, iOS)"
Sắp xếp Feature Area theo alphabet.

Kết quả agent trả về sẽ tương tự:

| Feature Area | Free | Pro | Enterprise |
|---|---|---|---|
| Auth | Email login | SSO Login (Web, iOS) | SSO Login (Web, iOS, Android), SCIM Provisioning |
| Billing | — | Invoice export | Custom billing cycle, Invoice export |
| Reporting | Basic dashboard | Custom dashboard | Custom dashboard, Scheduled export |

Bước tiếp theo hữu ích: yêu cầu agent tạo ngay một record mới trong một table khác (ví dụ Docs Snapshots) lưu lại bản feature matrix này kèm ngày tạo, để bạn có lịch sử feature matrix qua từng quý mà không cần tự copy-paste tay.

Lưu bảng feature matrix vừa tạo thành một record mới trong table
"Docs Snapshots": Title = "Feature Matrix Q3 2026",
Content = (nội dung Markdown vừa tổng hợp), Snapshot Date = hôm nay.

Mẹo: Khi tổng hợp ma trận từ dữ liệu multi-select (như Platform), luôn nhắc rõ agent cách xử lý khi một record thuộc nhiều giá trị cùng lúc (gộp vào một dòng hay tách nhiều dòng) — nếu không, agent sẽ tự chọn cách trình bày và có thể không khớp format bạn cần cho tài liệu cuối.

Các Hạn Chế Đã Biết Của Airtable MCP Trong OpenCode

Một vài giới hạn thực tế bạn nên biết trước, để không mất thời gian nghĩ rằng mình đang setup sai:

  • Không có UI approval trực quan cho tool call như một số IDE khác. OpenCode chạy chủ yếu ở terminal, nên việc "xác nhận trước khi ghi dữ liệu" phụ thuộc hoàn toàn vào cách bạn ràng buộc trong prompt/AGENTS.md, không có nút bấm approve/reject riêng cho từng field thay đổi như trong một số extension GUI.
  • Không tự động retry thông minh khi gặp rate limit 429. Một số phiên bản MCP server cơ bản chỉ trả lỗi thẳng lên agent; OpenCode agent sẽ thấy lỗi và tự quyết định retry hay không dựa trên system prompt, không có backoff strategy tích hợp sẵn ở tầng MCP client — với batch lớn, bạn nên chủ động yêu cầu "nghỉ vài giây giữa các batch" trong prompt.
  • Không hỗ trợ tốt file attachment lớn. Việc đọc/ghi field Attachment qua MCP tool cơ bản chỉ trả về URL, OpenCode không tự động download/preview nội dung file đính kèm (ảnh, PDF) — nếu cần agent "hiểu" nội dung file, bạn phải tự tải và cung cấp riêng.
  • Formula phức tạp dễ bị agent viết sai cú pháp Airtable. Cú pháp filterByFormula của Airtable khá đặc thù (hàm DATETIME_DIFF, IS_BEFORE...); agent OpenCode nói chung viết được các formula cơ bản tốt, nhưng với formula lồng nhiều điều kiện nested, nên luôn yêu cầu agent in ra công thức trước khi chạy để bạn review.
  • Không có cơ chế transaction. Nếu một batch update giữa chừng lỗi (ví dụ record thứ 6/10 có field type sai), các record 1-5 đã được ghi rồi không tự rollback — bạn cần tự yêu cầu agent báo cáo rõ record nào đã ghi thành công, record nào lỗi.

Mẹo: Với các workflow chạy lặp lại thường xuyên (ví dụ đồng bộ status hằng ngày), viết sẵn một prompt template chuẩn lưu trong file riêng của project (ví dụ .opencode/prompts/sync-status.md) rồi paste lại mỗi lần dùng, thay vì gõ tay lại từ đầu — giảm hẳn rủi ro quên các ràng buộc an toàn (batch size, xác nhận trước khi update) đã đề ra ở trên.

Mẹo Thực Chiến

  • Luôn dùng đúng schema key của OpenCode (mcp, type: "local", environment) — sao chép nguyên cấu hình từ client khác là nguyên nhân lỗi phổ biến nhất khi mới setup.
  • Bắt đầu mỗi phiên làm việc mới bằng bước mô tả schema table, đừng giả định agent còn nhớ từ phiên trước.
  • Đưa rule "luôn xác nhận trước khi update/delete" vào AGENTS.md của project để áp dụng nhất quán, không phải nhắc lại mỗi prompt.
  • Với formula filter phức tạp, luôn yêu cầu agent in công thức ra trước khi thực thi.
  • Chấp nhận rằng không có transaction — thiết kế mọi batch write để agent luôn báo cáo rõ record nào thành công/thất bại.

Mẹo: Nếu bạn dùng OpenCode cho nhiều project có base Airtable khác nhau, đặt cấu hình MCP ở cấp project (opencode.json trong repo) thay vì cấp global (~/.config/opencode/) — tránh việc agent vô tình đọc/ghi nhầm base của project khác khi bạn quên đổi context.

Tiếp Airtable MCP với Gemini CLI