Kết nối MCP

Quản lý tập trung các kết nối công cụ dùng lại được, rồi bật cho đúng những Agent thực sự cần.

MCP (Model Context Protocol) là một giao thức chuẩn để kết nối công cụ. Tạo một kết nối MCP trong Syfo là bạn có thể đưa các công cụ bên ngoài như Linear, API nội bộ… cho Agent dùng. Kết nối chỉ cần tạo một lần và có thể bật cho nhiều Agent; chỉ Agent được bật mới dùng được.

Lối vào: “Settings › MCP connections”. Bạn cũng có thể tạo mới trực tiếp trong thẻ “MCP” ở trang chi tiết Agent.

Bước 1: tạo kết nối

1. Vào “Settings › MCP connections”, nhấp “Create connection”.

2. Điền “Name” và “Description” (kết nối này dùng để làm gì).

3. Chọn “Scope” (phạm vi):

   • “Personal” (cá nhân): chỉ bạn thấy, chỉ bật được cho Agent do bạn phụ trách.
   • “Organization” (tổ chức): cả tổ chức thấy, Agent nào cũng có thể bật. Chỉ Owner hoặc Admin của tổ chức mới tạo và sửa được.

   Phạm vi được xác định khi tạo, sau đó không đổi được.

Bước 2: chọn phương thức truyền tải và điền cấu hình

Phương thức truyền tải	Phù hợp	Cần điền
Streamable HTTP	Dịch vụ MCP từ xa	URL; khi cần xác thực thì điền “Token”, giá trị này được chèn vào dưới dạng Bearer token
stdio	Chương trình MCP cục bộ khởi chạy trên máy tính nơi Agent chạy	Command, Args (mỗi dòng một tham số); khóa bí mật điền vào “Environment variables”, sẽ được chèn vào biến môi trường của tiến trình

• Sau khi lưu, token và biến môi trường không hiển thị lại giá trị gốc, chỉ hiển thị tên.
• Nếu đã có sẵn cấu hình JSON, bạn có thể chuyển sang “Advanced JSON” và dán trực tiếp.
• Khi tạo kết nối stdio trong thẻ “MCP” của Agent, bạn có thể đánh dấu “Bind to this computer”: lệnh và khóa bí mật chỉ được thực thi và cấp xuống trên máy tính này. Nếu không đánh dấu, bất kỳ máy tính nào chạy Agent đã bật kết nối này cũng sẽ thực thi lệnh và nhận được khóa bí mật.

Điền xong cấu hình thì nhấp “Create connection”.

Bước 3: kiểm tra

Trong danh sách kết nối, nhấp “Test”, kết quả có thể là:

• “Reachable”: kết nối được tới dịch vụ.
• “Auth required”: kết nối được tới dịch vụ, nhưng cần thông tin xác thực (credential) đúng.
• “Unreachable”: không kết nối được, hãy kiểm tra URL và mạng.
• “Error response”: dịch vụ trả về lỗi.

Kết nối stdio chạy trên máy tính nơi Agent chạy, phía máy chủ không kiểm tra được, sẽ hiện “stdio: test on agent host”. Với loại kết nối này, hãy chuyển thẳng sang bước tiếp theo và xem trạng thái chạy sau khi bật.

Bước 4: bật cho Agent

1. Mở trang chi tiết Agent, chuyển sang thẻ “MCP”.
2. Trong “Available connections”, tìm kết nối này và nhấp “Enable”. Chỉ người phụ trách Agent mới bật hoặc tắt được.
3. Trang sẽ hiện “MCP changes saved. If the Agent is currently running, restart it for the changes to take effect.” (thay đổi MCP đã được lưu; nếu Agent đang chạy, cần khởi động lại thì thay đổi mới có hiệu lực). Nhấp nút trong thông báo để khởi động lại Agent.

Khi không cần nữa thì nhấp “Disable”, cũng phải khởi động lại Agent mới có hiệu lực.

Bước 5: xem trạng thái chạy

Sau khi khởi động lại, quay về thẻ “MCP” của Agent để xem trạng thái từng kết nối:

• “Runtime health verified”: MCP khởi tạo thành công, Agent dùng được.
• “Runtime detected an unavailable MCP”: sẽ kèm lý do, ví dụ xác thực thất bại, không kết nối được dịch vụ, hoặc máy tính nơi Agent chạy thiếu lệnh, thư mục, quyền hay biến môi trường cần thiết.
• “Runtime health not verified”: chưa có kết quả chạy, thường là do Agent chưa khởi động lại hoặc chưa dùng đến kết nối.

“Inherited from runtime” là gì

Bên dưới thẻ “MCP” của Agent còn có một nhóm “Inherited from runtime · read-only” (kế thừa từ runtime, chỉ đọc). Đây là các MCP mà runtime Agent đang dùng (ví dụ Codex, Claude Code) tự cấu hình trên máy tính đó. Chúng do runtime quản lý; Syfo chỉ hiển thị, không bật, tắt hay sửa được.

Kết nối tạo trong Syfo không tự kế thừa từ Skill, kênh hay máy tính, mà phải được bật rõ ràng trên từng Agent.

Quản lý, thu hồi và xóa

Trong “Settings › MCP connections”, nhấp “Manage” để sửa cấu hình, xem “Agents using this connection” (các Agent đang dùng kết nối này), “Unbind” từng Agent hoặc “Unbind all”.

• Sau khi sửa cấu hình, Agent đang chạy phải khởi động lại mới dùng cấu hình mới.
• Khi “Revoke” một kết nối đang được dùng, mọi Agent dùng nó sẽ mất MCP này ở lần khởi động lại tiếp theo.
• Kết nối đang có Agent dùng thì không xóa được, cần tắt trên từng Agent trước. Xóa là không thể hoàn tác.

Thông tin xác thực và quyền

• Dùng thông tin xác thực riêng, với quyền tối thiểu.
• Đừng dán khóa bí mật vào kênh hoặc vào prompt của Agent. Thông tin xác thực cần lưu lâu dài và cấp quyền cho Agent thì hãy đưa vào Kho mật khẩu.
• Khi khách hàng hoặc ranh giới môi trường khác nhau, hãy tách thành các kết nối và thông tin xác thực riêng.
• Khi Agent hoặc dự án không cần nữa, hãy tắt kết nối và xoay vòng hoặc thu hồi thông tin xác thực.

Khắc phục sự cố

Khi kiểm tra kết nối thành công mà Agent vẫn không gọi được, hãy lần lượt kiểm tra:

1. Trong thẻ “MCP” của Agent này, kết nối đã được “Enable” chưa.
2. Sau khi bật hoặc sửa, đã khởi động lại Agent chưa.
3. Trạng thái chạy và lý do lỗi trong thẻ “MCP”.
4. Phạm vi quyền của thông tin xác thực, cũng như thiết lập quyền của chính dịch vụ bên ngoài.

Ghi chú

Kiểm tra thành công chỉ cho biết kết nối được tới dịch vụ, không có nghĩa là mọi Agent đều dùng được. Agent chỉ dùng được những kết nối đã được bật trên chính nó.