OpenCode là một trong những agentic coding tool mã nguồn mở phát triển nhanh nhất, hỗ trợ nhiều model provider (Anthropic, OpenAI, model local qua Ollama) và có hệ thống MCP client riêng khá linh hoạt. Nếu team bạn đang dùng OpenCode làm agent chính (thay vì Claude Code hay Cursor) vì muốn tự chọn model hoặc chạy self-hosted, bài này hướng dẫn cách kết nối GCP MCP vào OpenCode, cùng những khác biệt và hạn chế bạn cần biết trước khi tin tưởng nó cho các task liên quan dữ liệu thật.
Cài Đặt Và Kết Nối GCP MCP Với OpenCode
OpenCode dùng file cấu hình opencode.json (project-scoped, đặt ở root repo) hoặc ~/.config/opencode/config.json (global). Cấu trúc khai báo MCP server trong OpenCode hơi khác Claude Code — key là mcp thay vì mcpServers, và OpenCode yêu cầu khai báo rõ type: "local" cho server chạy qua stdio.
{
"mcp": {
"gcp-mcp": {
"type": "local",
"command": ["npx", "-y", "@google-cloud/mcp-server", "--project=my-gcp-project-id"],
"environment": {
"GOOGLE_APPLICATION_CREDENTIALS": "/Users/you/.config/gcloud/agent-mcp-sa-key.json"
},
"enabled": true
}
}
}
Lưu ý khác biệt nhỏ nhưng dễ gây lỗi: OpenCode dùng field command dạng array (mỗi phần tử là một token riêng), không phải string đơn với args tách riêng như Claude Code. Nếu bạn copy nguyên cấu hình từ Claude Code sang mà không sửa cấu trúc này, OpenCode sẽ báo lỗi parse config hoặc silent fail (server không khởi động mà không có thông báo rõ).
Sau khi lưu config, chạy opencode trong terminal, rồi dùng lệnh /mcp (tương tự Claude Code) hoặc kiểm tra qua TUI — OpenCode hiển thị trạng thái server ở panel bên dưới cùng giao diện chat. Nếu thấy gcp-mcp màu xanh/status "running" là kết nối thành công.
Một điểm cần lưu ý: OpenCode cho phép bật/tắt từng tool riêng lẻ trong cùng một MCP server qua field tools (whitelist), rất hữu ích khi bạn muốn agent chỉ thấy tool BigQuery đọc, không thấy tool Cloud Run hay GCS trong một session cụ thể:
{
"mcp": {
"gcp-mcp": {
"type": "local",
"command": ["npx", "-y", "@google-cloud/mcp-server", "--project=my-gcp-project-id"],
"tools": {
"bigquery_get_table_schema": true,
"bigquery_run_query": true,
"bigquery_dry_run": true,
"run_describe_service": false,
"gcs_list_objects": false
}
}
}
}
Mẹo: Khi mới setup, luôn bật whitelist tool tối thiểu cần cho task hiện tại (ví dụ chỉ BigQuery cho task phân tích dữ liệu) thay vì bật toàn bộ tool GCP MCP một lần — giảm rủi ro agent "lạc đề" sang gọi tool Cloud Run khi bạn chỉ cần nó viết SQL.
Truy Vấn BigQuery Dataset Và Liệt Kê Object Trên GCS Từ OpenCode
Workflow cơ bản trong OpenCode tương tự các agent khác, nhưng cách nó trình bày kết quả tool call trong TUI (terminal UI) có phần khác — mỗi tool call được hiển thị dạng block riêng, dễ theo dõi khi bạn cần audit lại agent đã gọi tool gì.
Ví dụ prompt liệt kê dataset và khám phá schema:
Dùng GCP MCP, list toàn bộ dataset trong project. Sau đó lấy schema của table
`logs.app_events` và cho tôi biết 5 giá trị phổ biến nhất của column `event_type`
trong 7 ngày gần nhất.
Agent sẽ gọi bigquery_list_datasets, sau đó bigquery_get_table_schema, và cuối cùng viết một query GROUP BY event_type ORDER BY COUNT(*) DESC LIMIT 5 kèm filter theo ngày, chạy qua bigquery_run_query. OpenCode hiển thị rõ input/output của từng tool call ngay trong terminal, giúp bạn xác nhận agent không viết sai tên column trước khi query thật chạy.
Với Cloud Storage, một use case phổ biến là kiểm tra file output của một batch job trước khi xử lý tiếp:
List các object trong bucket `my-data-lake` với prefix `exports/2026-07/`.
Cho tôi biết file nào mới nhất và kích thước bao nhiêu, tôi cần xác nhận
batch job tối qua đã export xong chưa.
Đây là pattern rất thực tế: thay vì bạn tự mở gsutil ls -l rồi lọc bằng mắt, agent trả lời trực tiếp "file mới nhất là exports/2026-07/part-00042.json, cập nhật 03:47 sáng, kích thước 240MB" — nhanh hơn và ít lỗi typo tên bucket/prefix.
Mẹo: Khi liệt kê object trên GCS với prefix rộng (ví dụ nguyên một tháng), luôn yêu cầu agent giới hạn số lượng kết quả trả về hoặc chỉ lấy N file mới nhất — một bucket log có thể chứa hàng trăm nghìn object, và việc list toàn bộ không giới hạn có thể khiến response quá dài, chậm, hoặc vượt context window.
Ví Dụ Thực Tế: Debug Một Cloud Run Deployment Bị Lỗi Trong OpenCode
Đây là kịch bản debug thường gặp: một service Cloud Run vừa deploy xong nhưng health check fail liên tục, container không lên trạng thái Ready.
Bắt đầu bằng prompt mô tả tình huống rõ ràng, tránh mô tả mơ hồ:
Service `notification-worker` vừa deploy revision mới nhưng không lên Ready.
Dùng GCP MCP: (1) describe service để xem trạng thái revision hiện tại,
(2) lấy log 50 dòng gần nhất của revision đó, (3) tóm tắt nguyên nhân fail
dựa trên log, đừng đoán nếu log không đủ thông tin.
Trong ví dụ thực tế tôi từng gặp, log trả về cho thấy container liên tục restart với message Error: connect ECONNREFUSED 127.0.0.1:6379 — agent phân tích đúng: service đang cố kết nối Redis ở localhost trong khi Cloud Run là môi trường container riêng biệt, không có Redis local. Nguyên nhân thực sự là biến môi trường REDIS_HOST bị thiếu trong revision mới (đã bị xóa nhầm khi cập nhật YAML deploy).
Sau khi xác định nguyên nhân, bạn có thể yêu cầu agent so sánh cấu hình biến môi trường giữa revision cũ (đang chạy ổn) và revision mới:
So sánh biến môi trường giữa revision `notification-worker-00018` (ổn định)
và `notification-worker-00019` (đang lỗi). Chỉ liệt kê phần khác biệt.
Đây là lúc GCP MCP tỏ ra vượt trội so với việc bạn tự debug bằng tay — agent đọc trực tiếp cấu hình revision qua API, không cần bạn tự nhớ hay tự diff hai file YAML deploy khác nhau.
Mẹo: Luôn yêu cầu agent trích dẫn nguyên văn dòng log làm bằng chứng khi đưa ra kết luận nguyên nhân lỗi — tránh trường hợp agent "đoán" nguyên nhân phổ biến (ví dụ luôn đổ lỗi cho memory limit) mà không dựa trên log thực tế của chính revision đang lỗi.
Các Hạn Chế Đã Biết Của GCP MCP Trong OpenCode
Tính đến thời điểm viết bài, OpenCode còn một số hạn chế khi dùng với GCP MCP mà bạn nên biết trước để không mất thời gian debug nhầm hướng.
Streaming tool output còn hạn chế: với query BigQuery trả về nhiều dòng dữ liệu, OpenCode có xu hướng buffer toàn bộ output trước khi hiển thị (khác với Claude Code có thể stream từng phần), nên với query trả về vài nghìn dòng, bạn sẽ thấy một khoảng chờ dài rồi hiện hết một lần — không phải lỗi, nhưng cần biết để không tưởng agent bị treo.
Không tự động dry-run mặc định: khác với một số cấu hình prompt mẫu cho Claude Code có sẵn quy tắc "luôn dry-run trước", OpenCode không có cơ chế system-level ép agent phải dry-run — bạn phải tự viết rõ yêu cầu này vào mỗi prompt hoặc vào file instructions riêng (AGENTS.md nếu project có, OpenCode có hỗ trợ đọc file này tương tự Claude Code đọc CLAUDE.md).
Whitelist tool theo tên chính xác, dễ typo: cấu hình tools whitelist ở trên yêu cầu bạn gõ đúng tên tool (case-sensitive), và OpenCode không luôn báo lỗi rõ ràng khi bạn gõ sai tên — tool đó chỉ đơn giản không xuất hiện, khiến bạn tưởng MCP server bị lỗi kết nối trong khi thực ra chỉ là gõ sai tên tool.
Một số phiên bản MCP server GCP chưa hỗ trợ đầy đủ pagination cho bigquery_run_query: nếu query trả về hàng chục nghìn row, một số bản OpenCode + GCP MCP server sẽ cắt kết quả ở một ngưỡng cố định (thường vài nghìn row) mà không cảnh báo rõ là đã bị truncate — luôn yêu cầu agent xác nhận rõ "kết quả này đã đầy đủ hay bị cắt" khi làm việc với dataset lớn.
Mẹo: Viết sẵn một file
AGENTS.mdở root project liệt kê rõ các quy tắc bắt buộc (dry-run trước, giới hạn LIMIT trong query, xác nhận kết quả không bị truncate) để bù lại việc OpenCode chưa có cơ chế ép buộc các quy tắc này ở tầng hệ thống.
Tips
- Luôn kiểm tra kỹ cấu trúc
commanddạng array khi cấu hình MCP server cho OpenCode — sao chép nhầm format từ Claude Code là lỗi phổ biến nhất khi mới chuyển sang. - Dùng whitelist tool để giới hạn phạm vi agent thấy được trong từng session, đặc biệt khi làm task chỉ cần đọc dữ liệu, không cần tool Cloud Run hay write.
- Với query BigQuery trả về dữ liệu lớn, luôn thêm
LIMITrõ ràng và tự hỏi agent xác nhận kết quả có bị truncate không, vì OpenCode chưa cảnh báo tự động điều này.