Cách Kết Nối Code Editor Tới MCP Server EzyPlatform [Hướng Dẫn Từng Bước]

MCP Server EzyPlatform giúp AI assistant truy vấn trực tiếp dữ liệu thực tế trên hệ thống, từ đó hiểu rõ cấu trúc và ngữ cảnh dự án thay vì chỉ viết code dựa trên phỏng đoán. Trong bài viết này, InterData sẽ hướng dẫn từng bước kết nối VS Code, Cursor và Windsurf với MCP Server EzyPlatform, bám sát tài liệu chính thức để bạn có thể cấu hình nhanh và sử dụng đúng cách.

MCP Server EzyPlatform là gì? Vì sao Code Editor cần kết nối?

MCP Server EzyPlatform là lớp giao tiếp dựa trên Model Context Protocol, cho phép AI assistant trong Code Editor truy vấn trực tiếp dữ liệu thật trên hệ thống EzyPlatform — bài viết, danh mục, template, cấu hình — thay vì viết code dựa trên phỏng đoán.

Khi bạn thực hành Vibe Coding trên EzyPlatform, AI cần hiểu cấu trúc dữ liệu thật đang chạy trên server: bảng nào có trường gì, fetcher nào đã tồn tại, event handler nào đang hoạt động. Không có kết nối MCP, AI chỉ sinh code mẫu chung chung. Có MCP, AI truy vấn schema, đọc dữ liệu, tạo fetcher và event handler — tất cả qua giao diện Code Editor quen thuộc.

MCP Server EzyPlatform hoạt động qua endpoint GraphQL tại đường dẫn /graphql/mcp trên admin URL. Kết nối được xác thực bằng access token, nghĩa là AI chỉ truy cập dữ liệu trong phạm vi quyền bạn cấp. Đây là điểm khác biệt lớn so với việc gọi API thủ công: AI tự khám phá danh sách tool có sẵn, tự chọn tool phù hợp và thực thi — bạn chỉ cần mô tả bằng ngôn ngữ tự nhiên.

Điều kiện tiên quyết trước khi kết nối MCP Server EzyPlatform

Trước khi tạo file cấu hình MCP, bạn cần đảm bảo hệ thống đã sẵn sàng. Thiếu một mục trong danh sách dưới đây sẽ khiến kết nối thất bại hoặc AI không nhận được tool nào.

Yêu cầu	Chi tiết	Kiểm tra
EzyPlatform đã cài đặt	Trên VPS, Cloud Server hoặc localhost. Cần domain + SSL cho kết nối từ xa.	Truy cập admin panel thành công
Plugin GraphQL đã cài	MCP Server chạy qua endpoint GraphQL. Không có plugin này = không có MCP.	Mục GraphQL xuất hiện trong admin
Plugin EzyArticle, EzySupport, Freestyle	EzyArticle lưu fetcher/event handler dưới dạng bài viết. EzySupport và Freestyle mở rộng khả năng tùy chỉnh.	Xuất hiện trong danh sách plugin admin
Access token admin	Lấy tại {admin_url}/admins/me → mục Access Token. Token xác thực quyền AI truy cập dữ liệu.	Copy token thành công
Code Editor hỗ trợ MCP	VS Code, Cursor AI, Windsurf, Cline — xem bảng so sánh ở mục tiếp theo.	Editor đã cài + AI assistant hoạt động
File environment.json (khuyên dùng)	Lưu thông tin kết nối EzyPlatform cho VS Code extension. AI có thể tự đọc file này để tạo .mcp.json.	File tồn tại trong thư mục dự án

File environment.json có cấu trúc như sau (theo tài liệu Chương 3 của EzyPlatform):

[
  {
    "name": "production",
    "default": true,
    "admin_url": "",
    "admin_access_token": ""
  },
  {
    "name": "beta",
    "admin_url": "",
    "admin_access_token": "",
    "notes": "This environment is optional and can be removed if not available."
  }
]

• name: tên môi trường, thường đặt “production” hoặc “staging”.
• admin_url: URL admin panel EzyPlatform (có HTTPS).
• admin_access_token: token lấy từ trang quản trị tài khoản admin.
• default: đặt true để AI tự chọn môi trường này khi kết nối.

Code Editor nào hỗ trợ MCP Server EzyPlatform?

MCP Server EzyPlatform sử dụng giao thức HTTP chuẩn (Model Context Protocol), nên bất kỳ Code Editor nào hỗ trợ MCP đều kết nối được. Dưới đây là 4 editor phổ biến nhất trong cộng đồng AI viết code hiện nay, cùng mức độ phù hợp khi dùng với EzyPlatform.

Code Editor	Hỗ trợ MCP	File cấu hình MCP	Ghi chú với EzyPlatform
VS Code + Claude Code / Codex	Có (qua AI assistant CLI)	.mcp.json trong thư mục dự án	Editor chính được tài liệu EzyPlatform hướng dẫn. Có extension EzyArticle đồng bộ nội dung.
Cursor AI	Có (tích hợp sẵn)	.cursor/mcp.json hoặc cấu hình trong Settings	Cú pháp JSON tương tự, đặt trong thư mục .cursor. Không có extension EzyArticle riêng.
Windsurf	Có (qua Cascade)	~/.codeium/windsurf/mcp_config.json hoặc cấu hình trong Settings	File cấu hình MCP đặt ở thư mục global. Cú pháp JSON giống nhau, khác vị trí lưu.
Cline (VS Code extension)	Có (tích hợp sẵn)	Cấu hình trong giao diện Cline Settings → MCP Servers	Thêm MCP Server qua UI, điền URL và header. Chạy trên VS Code nên vẫn dùng được extension EzyArticle.

Khuyến nghị: nếu mới bắt đầu, dùng VS Code + Claude Code vì đây là tổ hợp được tài liệu EzyPlatform hướng dẫn trực tiếp. Cursor và Windsurf áp dụng cùng nguyên lý, chỉ khác vị trí đặt file cấu hình — sẽ trình bày chi tiết ở mục 5.

Hướng dẫn từng bước kết nối Code Editor tới MCP Server EzyPlatform

Quy trình gồm 3 bước chính, theo tài liệu Chương 9 — MCP Server của EzyPlatform. Mỗi bước đều có code block cấu hình thật để bạn copy và điền thông tin của mình.

Bước 1: Cấu hình packages_to_scan trên admin EzyPlatform

Mục đích: khai báo cho plugin GraphQL biết cần quét những package nào để tạo endpoint MCP.

1/ Đăng nhập admin panel EzyPlatform.

2/ Vào GraphQL → Cài đặt (Settings).

3/ Dán đoạn cấu hình sau vào trường Configuration:

graphql.packages_to_scan=org.youngmonkeys.ezyarticle.web.controller.view,
org.youngmonkeys.ezyarticle.web.controller.api,
org.youngmonkeys.ecommerce.web.controller.view,
org.youngmonkeys.ecommerce.web.controller.api

• Cấu hình này cho GraphQL biết quét controller của EzyArticle và EzyCommerce để tạo các tool MCP tương ứng.
• Nếu bạn chỉ dùng EzyArticle (không dùng EzyCommerce), vẫn nên giữ nguyên cấu hình trên — các package không tồn tại sẽ được bỏ qua.

4/ Nhấn Lưu.

5/ Quay về Dashboard → Web, nhấn Khởi động lại (Restart) để áp dụng cấu hình mới.

Lưu ý quan trọng: Khởi động lại Web là bắt buộc. Nếu bỏ qua bước này, endpoint /graphql/mcp chưa được kích hoạt và Code Editor sẽ không kết nối được.

Bước 2: Tạo file .mcp.json trong thư mục dự án

File .mcp.json nằm ở thư mục gốc dự án, chứa thông tin kết nối để AI assistant tìm và giao tiếp với MCP Server. Đây là cú pháp chuẩn cho VS Code + Claude Code / Codex (theo tài liệu Chương 9):

{
  "mcpServers": {
    "{domain_name}": {
      "type": "http",
      "url": "{admin_url}/graphql/mcp",
      "headers": {
        "Authorization": "Bearer {admin_access_token}"
      }
    }
  }
}

Giải nghĩa từng trường:

• {domain_name}: tên định danh MCP Server, thường dùng tên domain admin. Ví dụ: freestyle-admin.ezyplatform.com. Bạn sẽ dùng tên này để kiểm tra kết nối ở Bước 3.
• "type": "http": giao thức kết nối. EzyPlatform MCP dùng HTTP transport.
• {admin_url}/graphql/mcp: endpoint MCP trên admin panel. Ví dụ: https://freestyle-admin.ezyplatform.com/graphql/mcp.
• Bearer {admin_access_token}: token xác thực, lấy từ trang /admins/me trong admin.

Ví dụ thực tế với domain 1576647146-admin.interdata.io.vn:

Nếu bạn đã có file environment.json trong dự án, AI assistant (Claude Code hoặc Codex) có thể tự đọc file đó và tạo .mcp.json tự động. Bạn chỉ cần yêu cầu như sau:

Lưu thông tin mcp server giúp tôi vào dự án này với cú pháp:
{
  "mcpServers": {
    "{tên miền của admin_url mặc định lấy từ tập tin environment.json}": {
      "type": "http",
      "url": "{admin_url mặc định lấy từ tập tin environment.json}/graphql/mcp",
      "headers": {
        "Authorization": "Bearer {admin_access_token mặc định lấy từ tập tin environment.json}"
      }
    }
  }
}

Bước 3: Kiểm tra kết nối MCP Server EzyPlatform

Sau khi tạo file .mcp.json, mở một phiên chat mới với AI assistant trong Code Editor (quan trọng: phải là phiên mới để AI đọc lại file cấu hình). Gõ câu hỏi kiểm tra:

Bạn kết nối được đến mcp server {domain_name} chứ?

Thay {domain_name} bằng tên bạn đã đặt trong file .mcp.json. Nếu AI trả lời xác nhận kết nối thành công và liệt kê được danh sách tool — bạn đã hoàn tất.

Nếu kết nối thất bại, xem bảng xử lý lỗi ở mục 7.

Cấu hình MCP Server EzyPlatform cho từng Code Editor

Phần trên hướng dẫn theo tài liệu chính thức EzyPlatform, sử dụng VS Code + Claude Code / Codex. Dưới đây là cách áp dụng tương tự cho Cursor và Windsurf. Nội dung JSON kết nối giống nhau — chỉ khác vị trí đặt file và cú pháp đặc thù của từng editor.

VS Code (theo tài liệu chính thức)

Tạo file .mcp.json ở thư mục gốc dự án. Claude Code và Codex tự đọc file này khi bắt đầu phiên chat mới. Cú pháp đã trình bày ở Bước 2.

Cursor AI (áp dụng tương tự)

Cursor hỗ trợ MCP qua file cấu hình đặt trong thư mục .cursor của dự án hoặc cấu hình global. Tạo file .cursor/mcp.json với nội dung:

{
  "mcpServers": {
    "{domain_name}": {
      "type": "http",
      "url": "{admin_url}/graphql/mcp",
      "headers": {
        "Authorization": "Bearer {admin_access_token}"
      }
    }
  }
}

Hoặc vào Cursor Settings → MCP, thêm server mới và điền URL endpoint cùng header Authorization. Sau khi lưu, mở chat mới để Cursor nhận MCP Server.

Windsurf (áp dụng tương tự)

Windsurf (Cascade) đọc cấu hình MCP từ file global tại ~/.codeium/windsurf/mcp_config.json hoặc qua Settings UI. Nội dung JSON tương tự:

{
  "mcpServers": {
    "{domain_name}": {
      "type": "http",
      "url": "{admin_url}/graphql/mcp",
      "headers": {
        "Authorization": "Bearer {admin_access_token}"
      }
    }
  }
}

Lưu ý: phần cấu hình cho Cursor và Windsurf ở trên là hướng dẫn áp dụng tương tự dựa trên cú pháp MCP chuẩn của từng editor, không phải nội dung từ tài liệu chính thức EzyPlatform. Cú pháp có thể thay đổi theo phiên bản editor — nên kiểm tra tài liệu MCP của từng editor để cập nhật.

Cline trên VS Code (áp dụng tương tự)

Cline là extension chạy trên VS Code, hỗ trợ MCP qua giao diện Settings. Mở Cline Settings → MCP Servers → Add Server, điền:

• Server URL: {admin_url}/graphql/mcp
• Header Authorization: Bearer {admin_access_token}

Cline chạy trên nền VS Code nên vẫn dùng được extension EzyArticle để đồng bộ nội dung song song.

5 nhóm công cụ MCP Server EzyPlatform sau khi kết nối

Sau khi kết nối thành công, AI assistant trong Code Editor có quyền sử dụng 5 nhóm tool. Mỗi nhóm phục vụ một mục đích khác nhau trong quy trình Vibe Coding trên EzyPlatform.

Nhóm công cụ	Chức năng	Ví dụ tool
Quản lý Fetcher	Tạo câu truy vấn dữ liệu mới, lưu dưới dạng bài viết, chạy khi được gọi. Script chạy trong JavaScript engine (Mozilla Rhino) với quyền truy cập data service.	create_graphql_fetcher_draft, validate_graphql_fetcher, save_graphql_fetcher
Quản lý Event Handler	Tạo kịch bản tự động chạy khi sự kiện xảy ra (thêm bài viết, cập nhật danh mục…). Bản nháp không tự kích hoạt — chỉ bản đã xuất bản mới chạy.	validate_event_handler, list_event_handlers, save_event_handler
Tra cứu dữ liệu	Truy vấn dữ liệu có sẵn (bài viết, trang, danh mục) mà không cần tạo fetcher mới.	search_posts, search_pages, admin_graphql_data_fetching
Quản lý cấu hình	Sửa template email, template nội dung, bản dịch i18n trực tiếp qua AI.	save_mail_template, save_content_template, save_i18n_messages
Tra cứu schema	Xem cấu trúc dữ liệu, kiểu dữ liệu, hàm có sẵn — giúp AI viết fetcher và event handler chính xác.	get_web_graphql_schema, get_admin_swagger

Quy trình an toàn khi AI tạo Fetcher và Event Handler

MCP Server EzyPlatform tuân theo quy trình an toàn nghiêm ngặt khi AI tạo fetcher hoặc event handler mới:

1. Kiểm tra trùng tên — AI tìm xem đã có fetcher/handler cùng tên chưa.
2. Nếu trùng, AI hỏi bạn: sửa cái cũ hay đặt tên khác.
3. Nếu mới, AI tạo bản nháp (draft) → validate cú pháp → xem trước cấu trúc dữ liệu trả về.
4. AI hỏi bạn: lưu nháp hay xuất bản (publish).
5. Chỉ khi bạn xác nhận xuất bản, fetcher/handler mới có hiệu lực ngay lập tức, không cần restart.

Quy trình này đảm bảo bạn luôn kiểm soát được những gì AI tạo ra trên hệ thống production. Bản nháp event handler không tự kích hoạt, nên bạn có thể thoải mái để AI thử nghiệm mà không lo ảnh hưởng dữ liệu thật.

Xử lý lỗi thường gặp khi kết nối MCP Server EzyPlatform

Dưới đây là các lỗi phổ biến nhất khi cấu hình kết nối Code Editor tới MCP Server EzyPlatform, kèm nguyên nhân và cách xử lý cụ thể.

Lỗi	Nguyên nhân	Cách xử lý
401 Unauthorized	Access token sai, hết hạn, hoặc thiếu prefix Bearer trong header.	Vào /admins/me tạo token mới. Kiểm tra cú pháp: "Authorization": "Bearer {token}" — có dấu cách sau Bearer.
AI không thấy tool nào	Chưa cấu hình packages_to_scan hoặc chưa restart Web sau khi lưu cấu hình GraphQL.	Kiểm tra lại Bước 1: dán đúng cấu hình packages_to_scan → Lưu → Dashboard → Restart Web.
Connection refused / timeout	URL admin sai, server chưa chạy, hoặc firewall chặn cổng.	Kiểm tra admin_url truy cập được từ trình duyệt. Nếu dùng VPS, kiểm tra firewall mở cổng HTTPS (443).
AI kết nối nhưng không trả dữ liệu	Plugin EzyArticle chưa cài hoặc chưa có dữ liệu mẫu trên hệ thống.	Cài plugin EzyArticle, tạo vài bài viết/danh mục mẫu, sau đó thử lại lệnh search_posts.
File .mcp.json không được nhận	File đặt sai thư mục, hoặc chưa mở phiên chat mới sau khi tạo file.	Đặt file ở thư mục gốc dự án (cùng cấp environment.json). Đóng phiên chat cũ, mở phiên mới để AI đọc lại cấu hình.
SSL certificate error	Domain chưa cài SSL hoặc SSL hết hạn.	Cài Let’s Encrypt SSL cho domain admin. MCP Server yêu cầu HTTPS khi kết nối từ xa.

Nếu đã kiểm tra tất cả mục trên mà vẫn lỗi, thử truy cập trực tiếp URL {admin_url}/graphql/mcp từ trình duyệt — nếu trả về lỗi 404, plugin GraphQL chưa cài hoặc chưa kích hoạt. Nếu trả về 403/401, vấn đề nằm ở token hoặc quyền truy cập.

Chọn hạ tầng chạy EzyPlatform và MCP Server EzyPlatform cho Vibe Coding

EzyPlatform chạy trên Java runtime, cần chạy nền liên tục, cần quyền root để cài plugin và cấu hình GraphQL. MCP Server yêu cầu endpoint HTTPS truy cập được từ Code Editor. Những yêu cầu này quyết định bạn cần loại hạ tầng nào.

Tiêu chí	VPS Vibe Coding	VPS tự cài	Cloud Server
EzyPlatform sẵn sàng	Tích hợp sẵn + plugin	Tự cài từ đầu	Tự cài từ đầu
MCP Server	Đã cấu hình sẵn	Tự cấu hình theo Bước 1	Tự cấu hình theo Bước 1
Quyền root	Có	Có	Có
Phù hợp	Bắt đầu Vibe Coding nhanh, 1 dự án	Tùy chỉnh sâu, nhiều dự án, chi phí thấp	Tải biến động, nhiều user, cần scale nhanh
Khi nào chọn	Muốn kết nối Code Editor tới MCP ngay, không muốn cài đặt	Đã quen Linux, muốn kiểm soát toàn bộ stack	Dự án lớn, team nhiều người, cần nâng/hạ tài nguyên

Nếu bạn chạy EzyPlatform trên localhost (máy cá nhân), MCP Server vẫn hoạt động nhưng AI chỉ kết nối được khi máy bật. Khi đưa code lên host sau khi Vibe Coding, bạn sẽ cần VPS hoặc Cloud Server để EzyPlatform chạy liên tục và MCP Server luôn sẵn sàng phục vụ.

EzyPlatform có thể triển khai qua Docker container trên VPS, giúp quản lý phiên bản và rollback dễ dàng hơn — phù hợp nếu bạn chạy nhiều dự án trên cùng một server.

Câu hỏi thường gặp về MCP Server EzyPlatform

MCP Server khác gì REST API thông thường?

REST API yêu cầu bạn tự viết request, biết endpoint, cấu trúc dữ liệu. MCP Server cho phép AI tự khám phá danh sách tool có sẵn, chọn tool phù hợp và thực thi dựa trên yêu cầu bằng ngôn ngữ tự nhiên. Bạn mô tả việc cần làm, AI tự quyết định gọi tool nào — không cần viết code gọi API thủ công.

MCP Server EzyPlatform có miễn phí không?

MCP Server là tính năng của plugin GraphQL trong EzyPlatform — bản thân EzyPlatform và plugin miễn phí. Chi phí phát sinh chủ yếu từ hạ tầng (VPS hoặc Cloud Server để chạy EzyPlatform) và subscription AI assistant (Claude Code hoặc Codex) mà bạn dùng trong Code Editor.

Có thể kết nối nhiều MCP Server cùng lúc trong một Code Editor không?

Có. File .mcp.json hỗ trợ nhiều entry trong object mcpServers. Mỗi entry là một MCP Server với tên, URL và token riêng. AI assistant sẽ nhận tất cả tool từ mọi server đã khai báo. Phù hợp khi bạn quản lý nhiều dự án EzyPlatform trên các server khác nhau.

Event handler bản nháp có tự chạy trên production không?

Không. Theo quy trình an toàn của MCP Server EzyPlatform, event handler ở trạng thái nháp (draft) không tự kích hoạt khi sự kiện xảy ra. Chỉ sau khi bạn xác nhận xuất bản (publish), handler mới có hiệu lực. Điều này cho phép AI thử nghiệm thoải mái mà không ảnh hưởng dữ liệu production.

Dùng Shared Hosting chạy EzyPlatform với MCP Server được không?

EzyPlatform cần Java runtime, quyền chạy process nền và cổng mạng riêng — những yếu tố mà Shared Hosting thường không cung cấp. Nếu bạn đang dùng Shared Hosting cho website nhỏ, nó vẫn phù hợp với nhu cầu đó. Khi cần chạy EzyPlatform + MCP Server, nên chuyển sang VPS hoặc Cloud Server để có quyền kiểm soát và tài nguyên cần thiết.

Nội dung mang tính tham khảo và được viết dựa trên tài liệu chính thức của EzyPlatform: Chương 3 — Chuẩn bị môi trường làm việc và Chương 9 — MCP Server. Giao diện admin, cú pháp cấu hình và tính năng MCP có thể thay đổi theo phiên bản EzyPlatform, plugin GraphQL và Code Editor bạn đang dùng. Nên kiểm thử trên môi trường staging, sao lưu dữ liệu và đối chiếu tài liệu mới nhất tại ezyplatform.com trước khi áp dụng cho production.