Cài vào Claude Code (plugin)¶

Plugin chính thức của Logidata cho Claude Code: kết nối một lần trên claude.ai, cài plugin bằng hai lệnh, xong. Không phải tự viết cấu hình MCP, không phải dán API key vào đâu cả, và không phải nhớ nền tảng nào gọi đường dẫn nào — plugin mang theo sẵn 11 kỹ năng phân tích biết chọn đúng endpoint cho từng câu hỏi.

Dùng Codex hoặc ChatGPT?

Có bản plugin riêng, cài theo cùng một mô hình — xem Plugin Codex / ChatGPT. Claude Desktop và Cherry Studio thì cắm tay, xem Kết nối MCP.

Hai mảnh ghép, đừng lẫn¶

Đây là chỗ hay gây rối nhất, nói trước cho gọn:

Mảnh	Cho bạn cái gì	Cài ở đâu
Trình kết nối (MCP qua OAuth)	dữ liệu — quyền gọi API nền tảng của bạn	một lần trên claude.ai, trong trình duyệt
Plugin	kỹ năng — trợ lý biết hỏi endpoint nào, dựng tham số ra sao	trong Claude Code, hai lệnh

Cả hai đều cần. Kết nối mà không có plugin thì trợ lý phải tự mò; plugin mà không có kết nối thì nó biết cách hỏi nhưng không có dữ liệu để hỏi.

Cài trong 3 bước¶

1. Kết nối Logidata trên claude.ai¶

Vào claude.ai → Cài đặt → Trình kết nối → Thêm trình kết nối tuỳ chỉnh, điền địa chỉ https://mcp.logidata.vn/mcp và Client ID claude-ai (Client Secret để trống) → Kết nối → đăng nhập tài khoản Logidata → Đồng ý.

Hướng dẫn từng bước kèm ảnh chụp màn hình: Kết nối MCP.

Cần gói Claude Pro, Max, Team hoặc Enterprise — trình kết nối tuỳ chỉnh không có ở bản miễn phí.

2. Cài plugin trong Claude Code¶

/plugin marketplace add getlogidata/agent-plugins
/plugin install logidata@logidata

3. Gõ `/logidata:setup`¶

Thấy đúng gói của bạn, các kết nối đang hoạt động và hạn mức còn lại là xong.

Kiểm tra nhanh nếu nghi ngờ

claude mcp list

Phải thấy dòng claude.ai Logidata: https://mcp.logidata.vn/mcp - ✔ Connected. Claude Code tự thừa hưởng trình kết nối từ tài khoản claude.ai của bạn — bạn không phải chạy claude mcp add gì cả.

Có gì trong plugin¶

11 kỹ năng, chia ba nhóm:

Nhóm	Kỹ năng	Khi nào dùng
Vận hành — gõ lệnh	`/logidata:setup`, `/logidata:quota`, `/logidata:doctor`	kiểm tra kết nối, xem hạn mức, chẩn lỗi từ mã lỗi
Phân tích — trợ lý tự chọn	`analyze-ads`, `analyze-orders`, `reconcile-finance`, `unify-platforms`, `analyze-youtube`, `analyze-search`	bạn chỉ cần hỏi bằng tiếng Việt
Tích hợp — trợ lý tự chọn	`generate-client`, `export-data`	sinh code Python/TypeScript, job xuất CSV/Sheets/Postgres

Kèm một subagent (logidata-analyst) cho báo cáo nhiều bước — nhiều advertiser, nhiều ngày, nhiều nguồn ghép lại — để cửa sổ hội thoại chính chỉ nhận kết luận và file, không nhận nguyên khối JSON.

Bạn không cần biết tên kỹ năng nào để dùng nhóm phân tích và tích hợp — cứ hỏi:

"7 ngày qua tôi tiêu bao nhiêu tiền quảng cáo TikTok Ads?"

"Người ta tìm gì để ra video của tôi?"

"Đối soát tiền về TikTok Shop kỳ gần nhất"

"Viết cho tôi script Python kéo báo cáo này mỗi sáng"

Nền tảng¶

Nền tảng	Ví dụ trợ lý trả lời được
TikTok Ads	Chi tiêu, CPC/CPM/CTR, hiệu suất chiến dịch
TikTok Shop	Đơn hàng, đối soát hai tầng, đơn affiliate
Shopee (kèm Shopee Ads, Shopee Affiliate)	Đơn hàng, escrow, hiệu suất CPC
Google Ads	Báo cáo GAQL, Keyword Planner
YouTube	Video, playlist, watch time, từ khoá người xem tìm ra kênh, doanh thu kênh (kênh đã bật kiếm tiền)
Google Search Console	Query thật người dùng gõ để vào website
Google Sheets	Đọc sheet của bạn làm bảng tra cứu, ghép với dữ liệu nền tảng

Trợ lý chỉ thấy phần nền tảng bạn đã cấp quyền ở Kết nối. Đây là danh sách nền tảng plugin biết gọi qua MCP — có thể khác bảng ở Nền tảng được hỗ trợ, vốn liệt kê toàn bộ REST API gateway (gồm cả những nền tảng chưa có đường qua MCP).

Cần biết trước¶

Mỗi lượt lấy dữ liệu tính 1 request vào hạn mức tháng, kể cả khi nền tảng trả lỗi. Các lượt tra danh mục (tìm endpoint, xem mô tả) thì miễn phí.
Tất cả chỉ đọc — không có đường nào sửa hay xoá chiến dịch, đơn hàng.
Phản hồi quá lớn bị cắt và đánh dấu truncated. Trợ lý sẽ tự thu hẹp khoảng ngày rồi hỏi lại, không kết luận trên phần đã cắt.
Kết nối tạo ra một API key tên "Claude (OAuth)" ở portal /keys. Thu hồi nó là cắt luôn quyền truy cập, chậm nhất sau một phút — không có token riêng nào phải nhớ thu hồi thêm.

Gỡ rối nhanh¶

Bạn thấy	Làm gì
Trợ lý không có công cụ Logidata nào	`claude mcp list` — thiếu dòng `claude.ai Logidata` thì làm lại bước 1
Có công cụ nhưng không có kỹ năng `/logidata:*`	`/plugin install logidata@logidata` chưa chạy xong — xem `/plugin`
"Chưa có kết nối nào"	Portal → Kết nối → cấp quyền nền tảng bạn cần
"Nền tảng này không có trong gói"	Portal → Nâng cấp
Hết hạn mức giữa chừng	Portal → Nâng cấp — mua thêm block

Ca nào không có ở đây thì gõ /logidata:doctor và dán nguyên văn lỗi — nó có bảng đầy đủ hơn, gồm cả các mã lỗi riêng của Google Ads, YouTube và Search Console.

Cả team dùng chung¶

Ghim marketplace vào .claude/settings.json của repo — git clone là có sẵn plugin cho cả team:

{
  "extraKnownMarketplaces": {
    "logidata": {
      "source": { "source": "github", "repo": "getlogidata/agent-plugins" }
    }
  },
  "enabledPlugins": { "logidata@logidata": true }
}

Mỗi người vẫn tự kết nối tài khoản Logidata của mình ở bước 1 — quyền truy cập không đi kèm repo.

Phụ lục — cắm bằng API key¶

Chỉ cần đến mục này nếu bạn không dùng tài khoản claude.ai (gói miễn phí, hoặc chạy Claude Code với API key Anthropic thuần). Luồng ở trên đơn giản hơn và nên là lựa chọn mặc định.

Lấy API key ở portal.logidata.vn/keys rồi:

claude mcp add logidata --transport http https://mcp.logidata.vn/mcp \
  --header "Authorization: Bearer ld_live_..."

Xong vẫn cài plugin như bước 2 để có 11 kỹ năng.

Key có giới hạn IP không dùng được

Kết nối đi qua hạ tầng Logidata nên máy chủ không thấy IP thật của bạn, và việc xác thực từ chối thay vì bỏ qua allowlist. Dùng một key để trống phần giới hạn IP. /logidata:doctor nhận ra và nói đúng nguyên nhân nếu bạn gặp 401 vì việc này.

Key vừa tạo mà báo 401 thì chờ một phút — bộ nhớ đệm 60 giây.

Plugin Codex / ChatGPT · Kết nối MCP · Mã lỗi · Xác thực