Hướng dẫn · EZG MCP

01Cần gì trước

Tài khoản Google công ty @easygoing.vn. Tài khoản khác bị từ chối.
Claude Code (CLI, app desktop hoặc extension IDE). Client MCP khác hỗ trợ Streamable HTTP + OAuth cũng kết nối được.
Chỉ khi cần cài / cập nhật vào project Unity: Unity Editor của project đang mở, có com.ezg.featurehub ≥ 0.4.0, và một Unity MCP có tool unity_execute_code đã kết nối vào cùng Claude Code. Tra cứu, kiểm tra cập nhật và duyệt đăng nhập không cần Unity.
Chỉ khi cần tạo project mới: macOS, hoặc Windows với Git Bash; Unity cài qua Unity Hub (không cần đang mở) và git.

02Cài đặt

Bước 1 — Thêm server một lần

Dùng cho mọi project trên máy:

Terminal

claude mcp add --transport http --scope user ezg https://mcp.easygoing.vn/mcp

Bước 2 — Đăng nhập

Trong Claude Code gõ /mcp → chọn ezg → Authenticate.
Trình duyệt mở trang “Cho phép Claude Code dùng EZG MCP?”. Bấm Sign in with Google và chọn tài khoản @easygoing.vn.
Trang báo “Xong — đang quay lại ứng dụng…”. Quay lại Claude Code: ezg đã kết nối.

Trang đồng ý ghi rõ quyền được gửi về đâu. Khi kết nối từ Claude Code, đó là một địa chỉ trên chính máy bạn (localhost / 127.0.0.1) — bình thường. Nếu bạn không vừa bấm kết nối, hãy đóng trang.

Dùng chung cho cả repo tuỳ chọn

Thay --scope user bằng --scope project để Claude Code ghi server vào .mcp.json ở gốc repo, rồi commit file đó:

.mcp.json

{
  "mcpServers": {
    "ezg": { "type": "http", "url": "https://mcp.easygoing.vn/mcp" }
  }
}

File không chứa token: mỗi người vẫn tự Authenticate bằng tài khoản của mình.

Các MCP khác của EZG tuỳ chọn

Cài khi cần, mỗi máy một lần (--scope user dùng cho mọi project). Khi tạo project mới, Claude sẽ hỏi bạn có muốn cài các server còn thiếu không; cũng có thể nói “Cài các MCP khác của EZG”.

ezg-project

project.easygoing.vn

Quản lý gói bán IAP trong các project

Terminal

claude mcp add --transport http --scope user ezg-project https://project.easygoing.vn/api/mcp
claude mcp login ezg-project

img-gen

img-gen.easygoing.vn

Generate image

Terminal

claude mcp add --transport http --scope user img-gen https://img-gen.easygoing.vn/api/mcp
claude mcp login img-gen

ezg-bot

ezg-bot.developer-a1f.workers.dev

Bot Discord (EZG Bot Control): slash command, channel, phân quyền, build GitLab

Terminal

claude mcp add --transport http --scope user ezg-bot https://ezg-bot.developer-a1f.workers.dev/mcp
claude mcp login ezg-bot

bughub

bug-reporter.developer-a1f.workers.dev

Bug QA log từ game (GitLab issue + thread Discord): đọc, nhận, báo đã sửa

Terminal

claude mcp add --transport http --scope user bughub https://bug-reporter.developer-a1f.workers.dev/mcp
claude mcp login bughub

ezg-cloud

ezg-cloud.developer-a1f.workers.dev

Cloudflare / Supabase / Firebase của từng project: API, SQL, deploy (server giữ key)

Terminal

claude mcp add --transport http --scope user ezg-cloud https://ezg-cloud.developer-a1f.workers.dev/mcp
claude mcp login ezg-cloud

ezg-gitlab

ezg-gitlab.developer-a1f.workers.dev

GitLab của các game: issue, MR, code, CI/CD, biến, thành viên — theo role trong directory (server giữ token)

Terminal

claude mcp add --transport http --scope user ezg-gitlab https://ezg-gitlab.developer-a1f.workers.dev/mcp
claude mcp login ezg-gitlab

ezg-sfx

ezg-sfx.developer-a1f.workers.dev

Sound effect / nhạc / ambience từ Freesound cho game (chỉ CC0 + CC BY): tìm, nghe thử, tải vào project, credits (server giữ key)

Terminal

claude mcp add --transport http --scope user ezg-sfx https://ezg-sfx.developer-a1f.workers.dev/mcp
claude mcp login ezg-sfx

ezg-3d

ezg-3d.developer-a1f.workers.dev

Thư viện model 3D của công ty (tìm, xem, tải model cho Unity)

Terminal

claude mcp add --transport http --scope user ezg-3d https://ezg-3d.developer-a1f.workers.dev/mcp
claude mcp login ezg-3d

notebook

notebook.easygoing.vn

Notebook nội bộ EZG: trang, block, database, file, thành viên và phân quyền

Terminal

claude mcp add --transport http --scope user notebook https://notebook.easygoing.vn/api/mcp
claude mcp login notebook

claude mcp login mở trình duyệt để đăng nhập; hoặc trong Claude Code gõ /mcp → chọn server → Authenticate.

Client khác

Claude Desktop, claude.ai, Cursor, VS Code…: thêm một MCP server kiểu HTTP với URL https://mcp.easygoing.vn/mcp rồi đăng nhập khi được hỏi. Các bước cài vào Unity cần Unity MCP chạy cùng client trên máy có Unity, nên client trên web chỉ dùng được phần tra cứu, kiểm tra cập nhật và duyệt đăng nhập.

03Kiểm tra kết nối

Terminal

claude mcp list

Dòng ezg phải báo đã kết nối. Hoặc hỏi Claude: “EZG MCP: tôi đang đăng nhập bằng tài khoản nào?” — tool whoami trả về email của bạn.

04Câu hỏi mẫu

Không cần nhớ tên tool: cứ nói bằng tiếng Việt, Claude tự chọn. Bấm một thẻ để copy câu hỏi.

05Các tool

44 tool, chia theo nhóm. Gõ để lọc theo tên hoặc mô tả.

Tool	Làm gì	Cần Unity?
Tài khoản & Feature Hub
`whoami`	Tài khoản Google của phiên MCP.	Không
`search_feature_hub`	Tìm package UPM (`com.ezg.*`), Unity package (`.unitypackage`), feature theo project (M001…), AI asset (skill / command / agent / rule cho `.claude/`). Lọc theo `kind`, `query`, `project`, `category`.	Không
`check_project_updates`	So `Packages/manifest.json` (và `install-record.json` nếu có) với Feature Hub. UPM lấy version của template làm đích và không bao giờ hạ cấp; bản mới hơn trong registry được báo kèm.	Không Claude đọc file trên máy
`get_install_steps`	Dữ liệu catalog đã xác minh + đoạn C# `install` và `verify`.	Có chạy đoạn C# qua Unity MCP
`new_project_instructions`	Các lệnh tạo project Unity sạch từ template EZG, y như double-click `build_unity_template.command`.	Unity đã cài, không cần mở
`companion_mcp_servers`	Các MCP khác của EZG (ezg-project, img-gen, ezg-bot, bughub, ezg-cloud, ezg-gitlab, ezg-sfx, ezg-3d, notebook) kèm lệnh kiểm tra, cài và đăng nhập. Claude luôn hỏi trước khi cài.	Không
Đăng nhập EZG cho máy
`login_instructions`	Các bước đăng nhập EZG cho máy: trong Unity, macOS / Linux, Windows.	Tuỳ cách
`approve_login`	Duyệt mã `XXXX-XXXX` bằng tài khoản của phiên MCP, thay cho trình duyệt.	Không
Google Sheets & localize
`gsheet_info`	Tên + các tab của một Google Sheet. Không truyền sheet: email service account để share.	Không
`gsheet_search`	Tìm chữ trên mọi tab (hoặc một tab): tab, ô, giá trị và cả dòng.	Không
`gsheet_read`	Đọc một tab / vùng (vd `A1:F50`) dạng bảng.	Không
`gsheet_write`	Ghi các ô khi bạn yêu cầu: xem trước, từ chối nếu ô đã bị người khác sửa, trả lại giá trị cũ để hoàn tác.	Không
`gsheet_delete_rows`	Xoá dòng khi bạn yêu cầu: xem trước, từ chối nếu dòng đã đổi (kiểm cột key), trả lại nội dung đã xoá để khôi phục.	Không
`localize_add_keys`	Phần sheet của skill `add-localize`: stage key ở tab `template`, chờ GOOGLETRANSLATE, ghi key đã dịch xong vào tab đích. Chạy theo vòng dưới 40 giây; Claude tự gọi tiếp tới khi xong và đưa từng phần vào project. Ô Google dịch lỗi được thử lại; key lỗi mãi thì Claude hỏi bạn (gõ tay / thử lại / bỏ qua).	Không
AutoBuild — build iOS / Android trên máy build của EZG
`autobuild_status`	Xem AutoBuild của project: nhánh build, máy build, biến CI/CD còn thiếu, lịch build hằng ngày, hạn của provisioning profile / chứng chỉ iOS / `CI_API_TOKEN` (báo trước 30 ngày).	Không
`autobuild_setup`	Setup AutoBuild cho project: gán runner máy 1 / máy 2, biến CI/CD (secret ký app dùng chung được copy ngay trên server, không đi qua chat), Discord channel bạn đưa, lịch build, pipeline trigger token (trả cho bạn: build không cần commit), và chạy pipeline đầu tiên (mặc định build + export, không upload store). Claude chạy installer tạo 2 nhánh build trên máy bạn. Chỉ Dev / Lead của project (role trong ezg-directory) hoặc owner / admin.	Không
`autobuild_schedule`	Tạo / sửa một lịch build trên nhánh build: dời giờ build hằng ngày, thêm lịch phụ (vd bản QA có cheat bằng define riêng), tạm dừng / bật lại. Trả id lịch để gắn vào lệnh build của Bot Control. Cùng quyền với `autobuild_setup`.	Không
`autobuild_ios_profile`	Đưa file `.mobileprovision` (App Store) của game lên AutoBuild: Claude chạy lệnh `curl` gửi file thẳng từ máy bạn lên server qua link có chữ ký (30 phút, chỉ project đó) — file không đi qua chat. Server kiểm loại profile, bundle id, team, hạn, chứng chỉ rồi mới set biến. Dùng cả khi gia hạn profile. Cùng quyền với `autobuild_setup`.	Không
`autobuild_run`	Chạy build (mặc định build + export, không upload store; `full` = như lịch, có upload; hoặc chọn bước), chạy lại một job, huỷ một pipeline — chỉ trên nhánh build. Trigger token nằm trên server. Từ chối kèm cách sửa khi thiếu biến / máy build / module cũ / đang có build chạy. Cùng quyền với `autobuild_setup`.	Không
`autobuild_upgrade`	Nâng (hoặc hạ) version module AutoBuild của nhánh build ngay trên server: một commit `[skip ci]` mỗi nhánh, giữ khối riêng trong `.gitlab-ci.yml`. Khi scaffold của module đổi thì trả lệnh installer. Cùng quyền với `autobuild_setup`.	Không
`autobuild_sync_secrets`	So secret dùng chung của game với project mẫu V3 / SM007 ngay trên server (không giá trị nào ra ngoài): nhóm thiếu thì copy, nhóm khác (chứng chỉ gia hạn, token hết hạn…) chỉ thay khi bạn xác nhận từng nhóm — game có thể có keystore / service account riêng. Kiểm cả bot Discord còn thấy channel changelog không. Cùng quyền với `autobuild_setup`.	Không
`autobuild_job_log`	Đọc log build (trace + file log Unity / xcodebuild trong artifacts) của một job, hoặc liệt kê các job build gần nhất để chọn job fail — Claude dò dòng lỗi rồi sửa code. Giá trị secret trong log được che `[REDACTED]`.	Không
Máy test mở cheat (cheat-gate)
`test_device_list`	Danh sách máy test được mở cheat trên bản release (package `com.ezg.cheat-gate`), theo project.	Không
`test_device_add` `test_device_remove`	Thêm / xoá máy test của một project (device ID `XXXX-XXXX-XXXX` game hiện khi tap version 10 lần). Chỉ Lead / QA của project (role trong ezg-directory) hoặc owner / admin.	Không
Danh bạ & quyền (ezg-directory)
`directory_whoami` `directory_projects`	Bạn là ai trong ezg-directory (owner / admin, role từng game — mọi app EZG đọc quyền từ đây) và danh sách game.	Không
`directory_people` `directory_members`	Danh bạ (owner, admin, Lead) và ai giữ role gì trong một game; Lead đặt role qa / dev / art / gd trong game mình lead.	Không
`directory_person_upsert` `directory_person_remove`	Thêm / sửa người (email, Discord, GitLab, role); tắt người nghỉ việc = chặn ở mọi app trong ~1 phút. Owner / admin (Lead: người mới vào game mình).	Không
`directory_grants`	Ai đang là root owner / owner / admin, ai cấp và lúc nào. Owner / admin.	Không
`directory_project_upsert` `directory_grant` `directory_people_sync` `directory_hr_sync` `directory_audit`	Owner / admin: tạo game, gắn GitLab; owner: cấp owner / admin, đồng bộ cả danh sách nhân viên, tắt người nghỉ việc theo HCNS; nhật ký thay đổi.	Không
Thông báo Discord (ezg-notify)
`notify_status`	Tin Discord của mọi dịch vụ EZG: công tắc tổng, kênh đích, luật, mute, số tin 24 giờ, tin chờ / bỏ cuộc, tin cuối của từng dịch vụ; `catalog: true` = mọi loại tin. Owner / admin.	Không
`notify_channel`	Kênh đích (alerts, changes…): xem / đặt (gửi tin thử trước, bot không đăng được thì không đổi) / gỡ / thử; ping role hoặc người khi critical. Owner đổi.	Không
`notify_rule`	Luật định tuyến theo nguồn / loại tin / project / mức độ → kênh hoặc tắt; `explain` = tin dạng này giờ đi đâu và vì sao. Owner đổi.	Không
`notify_mute`	Tạm tắt tin (tối đa 7 ngày, cần lý do); tin critical vẫn qua. Owner.	Không
`notify_settings`	Công tắc tổng, cửa sổ gộp tin trùng, số ngày giữ lịch sử. Owner đổi.	Không
`notify_history`	Lịch sử từng tin: được / không được đăng và vì sao, từng lần gửi; gửi lại (owner).	Không
Nhật ký
`audit_log`	Nhật ký mọi lần gọi tool của ezg-mcp (cả đọc, bị từ chối, lỗi), giữ 365 ngày: ai, lúc nào, tool nào, game nào, kết quả. Bạn xem được của mình; owner / admin xem của mọi người. Giá trị bí mật (token, mật khẩu…) và nội dung ô / bản dịch không bao giờ được ghi.	Không
Không có tool nào khớp.

Google Sheets dùng chung

Các tool gsheet_* (đọc, tìm, ghi ô, xoá dòng) và localize_add_keys chạy bằng service account của EZG; key nằm trên server, không ai cần (và không nên giữ) file key trong project hay trên máy. Một sheet chỉ dùng được khi chủ sheet đã Share cho ezg-game-docs@gameflow-500603.iam.gserviceaccount.com: quyền Viewer để đọc, Editor để ghi (add-localize, sửa sheet).

Trong project: skill game-docs đọc danh sách sheet ở .claude/project-profile.json → gameDocs.sources, skill add-localize đọc localize.sheet. Mọi lần ghi được lưu vết (ai, sheet nào, bao nhiêu ô / key nào).

06Tạo project Unity mới

Mở Claude Code trong một thư mục trống và nói “Tạo project Unity mới tên MyGame”. Claude gọi new_project_instructions rồi chạy đúng builder chính thức, nên kết quả giống hệt double-click build_unity_template.command:

Kiểm tra tên chưa bị dùng, chọn bản Unity đã cài (bản bạn nói, hoặc bản mới nhất không vượt giới hạn template đã kiểm thử), kiểm tra git.
Kiểm tra máy đã đăng nhập EZG; chưa thì đăng nhập qua approve_login (mục 08), không cần mở trình duyệt.
Tải bootstrap từ gateway (bản logic được kiểm SHA-256) và chạy builder ở chế độ nền: tạo project, ghi manifest, import SDK, áp DefaultSetup (ProjectSettings, .claude/, .mcp.json…), resolve package bằng Unity headless, git init.
Báo kết quả khi xong và mở project trong Unity.
Hỏi bạn có muốn cài các MCP khác của EZG còn thiếu trên máy (mục 02) không.

Lệnh Claude chạy trên macOS (Windows dùng build_unity_template.sh trong Git Bash, cùng tham số):

Terminal

curl -fsSL https://upm-registry-worker.developer-a1f.workers.dev/boot/build_unity_template.command -o build_unity_template.command
bash build_unity_template.command --project-name 'MyGame' --unity-version <bản Unity đã cài> --no-pause

Thường mất 5–20 phút (bước Unity headless). Claude chạy nền và báo khi xong.

Project nằm ở ./MyGame trong thư mục hiện tại. Không muốn Unity tự mở khi xong: nói thêm “đừng mở Unity”.

07Cập nhật project Unity

Nói “Cập nhật project này theo Feature Hub”. Claude làm theo trình tự sau (mở sẵn Unity Editor của project):

Đọc Packages/manifest.json và ProjectSettings/EzgFeatureHub/install-record.json (nếu có). Thiếu install record thì chỉ kiểm được package UPM.
Gọi check_project_updates để lấy danh sách mục update_available.
Với từng mục: get_install_steps rồi chạy đoạn install bằng unity_execute_code. Làm từng mục một: import .unitypackage có thể gây domain reload.
Chạy đoạn verify (cùng tool) đến khi báo INSTALLED, hoặc xem Console các dòng bắt đầu bằng [ezg-mcp].

Trạng thái	Nghĩa là
update_available	Có bản mới hơn — trường `updateTo` là version sẽ cài.
up_to_date	Đã đúng bản của template / catalog.
pinned_non_registry	Package trỏ git URL / `file:` / embedded. Feature Hub để nguyên.
unknown_package not_in_catalog	Không có trong registry / catalog của EZG.

08Đăng nhập EZG cho máy

Feature Hub (tải package) và Unity Package Manager (package com.ezg.*) cần máy có phiên EZG. Cách nhanh nhất: nói “Đăng nhập EZG cho máy này” — Claude gọi login_instructions, chạy lệnh, rồi approve_login với mã máy vừa hiện. Không cần mở trình duyệt.

Tự làm

Trong Unity

Cần com.ezg.featurehub ≥ 0.3.0: menu Ezg › Đăng nhập EZG → cửa sổ hiện mã XXXX-XXXX → bảo Claude “duyệt mã XXXX-XXXX” (hoặc mở link trong cửa sổ bằng trình duyệt).

macOS / Linux

Terminal

curl -fsSL https://mcp.easygoing.vn/cli/ezg-login.sh | bash

Cần curl và python3. Script in mã rồi chờ tối đa 3 phút; trong lúc đó bảo Claude duyệt mã hoặc mở link nó in ra.

Windows

PowerShell

irm https://mcp.easygoing.vn/cli/ezg-login.ps1 -OutFile $env:TEMP\ezg-login.ps1; powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\ezg-login.ps1

PowerShell 5.1+, cùng cách dùng.

Xem phiên hiện tại: thêm status vào cuối — … | bash -s -- status trên macOS / Linux, … ezg-login.ps1 status trên Windows.

Phiên được lưu ở ~/.ezg/credentials.json và ~/.upmconfig.toml (chỉ chủ máy đọc được). Token không bao giờ được in ra hay đi qua Claude.

Mã hết hạn sau 10 phút. Chỉ duyệt mã do chính máy bạn vừa hiện — kết quả approve_login ghi tên máy để đối chiếu.

Unity đã báo lỗi 401 trước đó? Window › Package Manager › Refresh, hoặc mở lại Editor.

09Bảo mật & phiên

Chỉ @easygoing.vn

Chỉ tài khoản Google Workspace @easygoing.vn (kiểm cả domain Workspace lẫn đuôi email).

Phiên 24 giờ / 30 ngày

Access token sống 24 giờ và tự làm mới. Sau 30 ngày phải Authenticate lại với Google.

Chặn có hiệu lực ngay

Admin chặn một người ở /admin của gateway → người đó mất quyền ngay ở request tiếp theo, kể cả khi làm mới token.

Không ghi gì vào máy bạn

EZG MCP không ghi gì vào máy hay project của bạn. Mọi thay đổi trong project là do Claude chạy trên máy bạn (Unity MCP, script của skill).

Key Google ở server

Key service account chỉ nằm trong secret của server; tool trả dữ liệu sheet, không bao giờ trả key hay token. Service account chỉ thấy sheet được share cho nó.

Nhật ký mọi lần gọi

Mỗi lần gọi tool được ghi (ai, tool, game, kết quả) và giữ 365 ngày; giá trị bí mật không bao giờ được ghi. Xem bằng audit_log.

10Xử lý sự cố

/mcp báo ezg cần xác thực hoặc lỗi kết nối

/mcp → ezg → Authenticate lại. Sau 30 ngày đây là chuyện bình thường.

“Chỉ tài khoản Google công ty được phép đăng nhập.”

Chọn đúng tài khoản @easygoing.vn trên nút Google.

“Tài khoản này đã bị chặn. Liên hệ admin.”

Liên hệ admin.

Trang “Không thể cho phép” / phiên đăng nhập hết hạn

Bắt đầu lại từ Claude Code: /mcp → ezg → Authenticate.

Claude không có tool unity_execute_code

Kết nối Unity MCP vào Claude Code và mở Unity Editor của project.

Đoạn C# báo lỗi không tìm thấy Ezg.FeatureHub.Editor

Cập nhật com.ezg.featurehub lên ≥ 0.4.0.

verify báo NOT_INSTALLED

Đợi vài giây (domain reload) rồi chạy lại verify; xem Console các dòng [ezg-mcp].

Tạo project dừng với lỗi

Xem các dòng ERROR trong build_unity_template.last-run.log cạnh file bootstrap. Lỗi resolve package thường do thiếu git hoặc máy chưa đăng nhập EZG.

“Mã không tồn tại hoặc đã hết hạn”

Lấy mã mới (mã sống 10 phút) rồi duyệt lại.

Tool gsheet_* / localize_add_keys báo không có quyền

Chủ sheet Share cho ezg-game-docs@gameflow-500603.iam.gserviceaccount.com (Viewer để đọc, Editor để ghi) rồi thử lại.

Thêm key localize báo needs_attention

Google dịch một ngôn ngữ lỗi liên tục (thường là "Google Translate internal error."). Gõ tay ngôn ngữ đó, thử lại sau, hoặc bỏ key — Claude dùng retry_call, không stage lại.

add_localize.py báo không biết --apply-url

Skill add-localize trong project đã cũ: cập nhật từ Feature Hub (tab AI Feature).

“chưa có service account Google (GOOGLE_SA_KEY)”

Báo admin EZG.

Package Manager báo 401 với com.ezg.*

Đăng nhập EZG cho máy (mục 08) rồi Refresh Package Manager.

11Gỡ bỏ

Terminal

claude mcp remove ezg --scope user

Dùng --scope project nếu đã thêm theo repo (hoặc xoá mục ezg trong .mcp.json).