Kết nối máy chủ MCP
Máy chủ MCP của Aggrega là lệnh aggrega mcp, và tệp nhị phân aggrega là điều kiện tiên quyết duy nhất của nó: Cài đặt tệp nhị phân cài đặt tệp này bằng một lệnh. Máy chủ chạy như một tiến trình con của client qua stdio, đọc các schema từ tệp nhị phân và các trang tài liệu từ một bản sao mà nó tải một lần vào bộ nhớ đệm của máy bạn, và không cần dịch vụ, cổng hay tài khoản riêng nào. Nếu đã có người khác chạy máy chủ cho bạn, bạn không cần tệp nhị phân hay bất kỳ điều nào ở đây: xem Máy chủ được truy cập qua HTTPS.
Các client thêm máy chủ bằng một lệnh
Một trợ lý đã cài đặt plugin Aggrega thì đã được kết nối sẵn. Việc cài đặt plugin thêm kỹ năng Aggrega và máy chủ trong một bước — trong Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro và OpenClaw, như Cài đặt plugin mô tả — nên không cần gì khác trên trang này để kết nối trợ lý đó. Plugin khởi động aggrega mcp bằng aggrega được tìm thấy trên PATH mà trợ lý được khởi động cùng, vì vậy tệp nhị phân phải được cài đặt ở đó. Một số trợ lý khởi động máy chủ của plugin trong thư mục riêng của plugin thay vì trong dự án của bạn — Codex làm như vậy — và khi đó trợ lý chỉ định thư mục dự án của bạn làm workspace_root trong các lệnh gọi chấp nhận tham số đó; kỹ năng yêu cầu trợ lý kiểm tra xem máy chủ trả lời trong workspace nào.
Không có plugin, hãy thêm máy chủ bằng lệnh riêng của client. Trong Claude Code:
claude mcp add --transport stdio aggrega -- aggrega mcpTrong Codex:
codex mcp add aggrega -- aggrega mcpTrong Gemini CLI:
gemini mcp add aggrega aggrega mcpMọi client khác
Hầu hết các client hỗ trợ MCP khởi chạy máy chủ theo cùng một cách — chúng chạy lệnh aggrega với một đối số duy nhất mcp và giao tiếp theo giao thức qua đầu vào và đầu ra chuẩn của tiến trình. Điểm khác nhau giữa chúng là nơi mỗi client lưu danh sách máy chủ và cách nó gọi các mục trong đó. Dạng chung:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Khi client khởi động lại và kết nối, các prompt, tài nguyên và công cụ soạn thảo của Aggrega sẽ sẵn sàng. Những gì trợ lý của bạn có thể làm với Aggrega mô tả chúng, Viết tệp Aggrega chỉ ra nên làm gì với chúng, và tài liệu tham chiếu aggrega mcp trình bày về chính lệnh này.
Không có gì trong mục cấu hình chọn một phiên bản sửa đổi của giao thức. Aggrega hỗ trợ cả 2026-07-28 và 2025-06-18, qua đầu vào và đầu ra chuẩn cũng như qua HTTPS, nên client của phiên bản nào cũng kết nối được và tiếp cận cùng các prompt, tài nguyên và công cụ. Client yêu cầu phiên bản nào được quyết định trong quá trình giao tiếp chứ không phải trong cấu hình của bạn.
Một trợ lý có thể chạy lệnh có thể tự làm tất cả những việc này — cài đặt tệp nhị phân, thêm skill Aggrega, và kết nối tới máy chủ — từ một prompt bạn dán vào: xem Thiết lập Aggrega với trợ lý AI của bạn.
Nơi mỗi client lưu danh sách máy chủ
| Client | Vị trí của danh sách | Tên gọi của mục |
|---|---|---|
| Claude Code | claude mcp add, hoặc một tệp .mcp.json trong dự án | mcpServers |
| Claude Desktop | cài đặt tiện ích mở rộng của nó cho máy chủ cục bộ; cài đặt trình kết nối của nó cho máy chủ được truy cập qua HTTPS | xem Claude Desktop |
| Cursor | .cursor/mcp.json cho một workspace, hoặc một mcp.json ở phạm vi người dùng cho mọi workspace | mcpServers |
| Gemini CLI | gemini mcp add, hoặc ~/.gemini/settings.json cho mọi dự án và .gemini/settings.json cho một dự án | mcpServers |
| Codex CLI | codex mcp add, hoặc ~/.codex/config.toml cho mọi dự án và .codex/config.toml cho một dự án được tin cậy | một bảng [mcp_servers.aggrega] — xem Codex CLI |
| Zed | Settings → AI → MCP Servers, nơi ghi mục cấu hình vào tệp thiết lập của Zed | context_servers — xem Zed |
| Visual Studio Code | mcp.json trong hồ sơ người dùng của bạn, hoặc .vscode/mcp.json cho một workspace | servers — xem Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add, hoặc tệp mcp-config.json mà nó lưu trong thư mục home của bạn | mcpServers |
| Antigravity | tệp mcp_config.json có thể truy cập từ phần cài đặt của nó | mcpServers |
| Windsurf | tệp mcp_config.json có thể truy cập từ phần cài đặt của nó | mcpServers |
| Cline | cài đặt MCP của nó, được lưu trong một tệp cline_mcp_settings.json | mcpServers |
Mọi client trong bảng đó, trừ bốn client có mục riêng bên dưới, đều nhận mục cấu hình đúng như đã viết ở trên, tại đường dẫn trong hàng của nó. Một client không được liệt kê cũng kết nối theo cùng cách nếu nó đọc danh sách máy chủ ở một trong các dạng này.
Lưu ý về PATH
Các client được khởi chạy từ môi trường đồ họa không phải lúc nào cũng kế thừa cùng PATH với terminal của bạn. Nếu một client báo rằng nó không tìm thấy lệnh aggrega, hãy thay "command": "aggrega" bằng đường dẫn tuyệt đối tới tệp nhị phân (ví dụ "command": "/home/you/.local/bin/aggrega", vị trí cài đặt trên Linux cho người dùng tên là you). Mọi thứ khác giữ nguyên.
Visual Studio Code
Visual Studio Code lưu các máy chủ của nó trong servers thay vì mcpServers, và mỗi mục nêu rõ phương thức truyền tải mà nó dùng:
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex lưu các máy chủ của nó bằng TOML thay vì JSON — trong ~/.codex/config.toml cho mọi dự án, hoặc trong .codex/config.toml cho một dự án mà Codex tin cậy — mỗi máy chủ là một bảng được đặt theo tên máy chủ:
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp, lệnh ở phía trên, ghi cùng bảng đó cho bạn. Tiện ích mở rộng Codex cho IDE và ứng dụng ChatGPT trên máy tính đọc cùng tệp đó, nên một mục cấu hình phục vụ cả ba.
Zed
Zed lưu các máy chủ của nó dưới context_servers trong tệp thiết lập. Thêm máy chủ từ Settings → AI → MCP Servers — Add Server, rồi Add Local Server — thao tác này ghi mục cấu hình vào tệp đó, hoặc chạy zed: open settings file từ bảng lệnh và tự thêm mục cấu hình:
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed hỗ trợ các công cụ và prompt của giao thức, nên agent của nó tiếp cận được các công cụ và prompt soạn thảo của Aggrega nhưng không tiếp cận được các tài nguyên mà máy chủ cũng cung cấp.
Claude Desktop
Claude Desktop cài đặt một máy chủ cục bộ từ một gói tiện ích mở rộng — máy chủ cùng với một manifest mô tả nó, được đóng gói thành một tệp có thể cài đặt và được thêm từ phần cài đặt tiện ích mở rộng — thay vì từ một mục trong tệp cấu hình. Mỗi bản phát hành của Aggrega đều kèm một gói như vậy, aggrega-<version>.mcpb, bên cạnh các tệp nhị phân dựng sẵn.
Gói của Aggrega không chứa chương trình riêng nào. Nó khởi chạy một tệp thực thi aggrega đã được cài đặt sẵn trên máy của bạn, với đối số duy nhất mcp, và giao tiếp theo giao thức qua đầu vào và đầu ra chuẩn của tiến trình đó — cùng một máy chủ mà mọi mục ở trên khởi chạy. Trừ khi bạn chọn một tệp thực thi khác, nó giao cho Claude Desktop tên lệnh aggrega, như mọi mục ở trên, nên ứng dụng tìm aggrega trong PATH có hiệu lực khi ứng dụng được khởi chạy; và nó giao cho máy chủ đó workspace mà bạn chọn. Để thêm nó:
- Cài đặt tệp nhị phân
aggrega, như mô tả trong Cài đặt tệp nhị phân. Lệnh cài đặt và các bước thủ công ở đó đều giữ nó trong một thư mục của riêng bạn — trên Windows là%LOCALAPPDATA%\Programs\aggregathay vì một thư mục hệ thống nhưC:\Windows\System32— để bạn có thể thay thế nó mà không cần quyền quản trị. - Cài đặt
aggrega-<version>.mcpbtừ phần cài đặt tiện ích mở rộng của Claude Desktop. - Đặt các thiết lập của gói; không thiết lập nào là bắt buộc. Path to the aggrega executable là chương trình mà gói khởi chạy, và giá trị mặc định của nó là tên lệnh
aggrega, mà ứng dụng tìm trongPATHcó hiệu lực khi ứng dụng được khởi chạy. Một thư mục được thêm vàoPATHcủa bạn trong khi ứng dụng đang chạy — như trình cài đặt Windows và lệnh cài đặt trên Windows thêm thư mục của chúng — chỉ đến được với ứng dụng sau khi ứng dụng đã thoát và khởi động lại, như ở bước 4, và một ứng dụng được khởi chạy từ môi trường đồ họa có thể không thấy cùngPATHvới terminal của bạn (xem Ghi chú vềPATH). Hãy giữ giá trị mặc định khiaggregatrongPATHđó là tệp thực thi bạn muốn. Thay vào đó, hãy đặt trường thành đường dẫn đầy đủ của một tệp thực thi khi tệp bạn muốn không nằm trongPATHđó, hoặc là mộtaggregakhác với tệp đầu tiên được tìm thấy ở đó — trên macOS và Linux, với vị trí cài đặt, làaggregatrong.local/binthuộc thư mục home của bạn, chẳng hạn/Users/you/.local/bin/aggrega; trên Windows là đường dẫn đầy đủ kết thúc bằngaggrega.exe, chẳng hạnC:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Để quay lại giá trị mặc định, hãy đặt trường thànhaggregathay vì để trống. Nếu hoàn toàn chưa cài đặtaggreganào, hãy cài đặt nó như bước 1 mô tả. Workspace folder là thư mục của workspace Aggrega mà trợ lý làm việc trong đó: thư mục chứa.aggrega-config.yamlcủa dự án bạn. Hãy đặt thiết lập này: nó để trống cho đến khi bạn chọn một thư mục, và trong khi nó trống, gói giao cho máy chủ mộtAGGREGA_WORKSPACE_ROOTtrống, nên máy chủ trả lời mọi yêu cầu mà trợ lý đưa ra trong workspace bằng một lời từ chối cho biết thiết lập Workspace folder đang trống và yêu cầu bạn đặt nó thành thư mục chứa.aggrega-config.yamlcủa workspace, thay vì làm việc trong thư mục mà Claude Desktop đã khởi động nó. Gói chỉ giao thư mục cho máy chủ khi ứng dụng khởi động máy chủ, nên một thư mục bạn đặt trong khi máy chủ đang chạy chỉ có hiệu lực sau khi bạn tắt rồi bật lại tiện ích mở rộng trong phần thiết lập tiện ích mở rộng, hoặc khởi động lại ứng dụng như ở bước 4. - Thoát hoàn toàn Claude Desktop, rồi khởi động lại. Một máy chủ mà ứng dụng đã khởi động sẽ tiếp tục chạy, và việc đổi tên tệp thực thi không dừng nó, nên một thiết lập đã thay đổi chỉ có hiệu lực khi ứng dụng khởi động lại máy chủ: sau khi ứng dụng đã thoát và khởi động lại, hoặc, với Workspace folder, sau khi tiện ích mở rộng được tắt rồi bật lại. Trên Windows, Task Manager cho biết liệu một tiến trình
aggregacó còn đang chạy hay không.
Thư mục workspace là nơi trả lời mọi yêu cầu không nêu workspace riêng. Claude Desktop khởi động máy chủ trong một thư mục do nó tự chọn thay vì trong dự án của bạn, nên gói chuyển thư mục bạn chọn cho máy chủ dưới dạng biến AGGREGA_WORKSPACE_ROOT trong môi trường của nó, thay vì dưới dạng đối số trên dòng lệnh mà ứng dụng tạo ra. Máy chủ lấy chính thư mục đó làm thư mục gốc của workspace, giống như --workspace-root được dùng trên mọi lệnh: nó không tìm lên phía trên để tìm một workspace bao quanh, vì vậy hãy chọn thư mục chứa .aggrega-config.yaml chứ không phải một thư mục bên trong nó. Để làm việc trong workspace khác, hãy thay đổi thiết lập và khởi động lại ứng dụng như ở bước 4. Với một yêu cầu nêu workspace riêng bằng một workspace_root tương đối, đường dẫn đó cũng được đọc từ thư mục workspace, nên một lời nhắc có thể nêu một thư mục bên trong nó — chẳng hạn quickstart-ai/1 — mà không cần biết thư mục đó nằm ở đâu trên máy của bạn; một workspace_root tuyệt đối được dùng đúng như đã cho. Khi thiết lập còn trống, một đường dẫn tương đối nhận cùng lời từ chối như một yêu cầu không nêu workspace nào.
Vì gói không nêu tệp thực thi của nền tảng nào, cùng một tệp áp dụng cho mọi nền tảng mà nó khai báo: macOS, Windows và Linux.
Máy chủ báo cho biết gói đã khởi chạy aggrega nào. Phần cài đặt tiện ích mở rộng của Claude Desktop liệt kê phiên bản của chính gói — phiên bản của bản phát hành mà nó đến từ đó — chứ không phải phiên bản của tệp thực thi mà nó khởi chạy. Hai thứ này được cài đặt riêng, nên có thể đến từ các bản phát hành khác nhau. Gói giao phiên bản của chính nó cho máy chủ dưới dạng biến AGGREGA_BUNDLE_VERSION trong môi trường, và máy chủ báo cả hai: câu trả lời của describe-capabilities khi được gọi không có đối số — công cụ mà trợ lý gọi để biết máy chủ cung cấp gì — mở đầu bằng một dòng nêu phiên bản của tệp thực thi và của gói, và mang cùng dòng đó dưới dạng version_summary trong phần có cấu trúc, để một trợ lý được hỏi phiên bản Aggrega nào đang chạy có thể đọc cả hai ở đó, bất kể ứng dụng giao cho nó phần nào của câu trả lời. Khi hai thứ đến từ các bản phát hành khác nhau, dòng đó nói rõ điều này, nêu cả hai, và phần hướng dẫn mà máy chủ giao cho trợ lý khi kết nối cũng mở đầu bằng cùng câu đó. Không có gì bị từ chối vì sự khác biệt, và máy chủ trả lời mọi yêu cầu như bình thường; điều này được báo để bạn biết gói đang chạy tệp thực thi nào. Để đồng bộ hai thứ, hãy cài đặt aggrega-<version>.mcpb của bản phát hành mà tệp thực thi của bạn đến từ đó — aggrega version trong terminal sẽ in ra phiên bản đó — hoặc đặt Path to the aggrega executable thành đường dẫn đầy đủ của một aggrega thuộc bản phát hành của gói, rồi khởi động lại ứng dụng như ở bước 4.
Nhật ký riêng của Claude Desktop cho biết nó đã khởi chạy gì. Trên Windows, chúng có thể nằm trong một thư mục gói thuộc thư mục dữ liệu ứng dụng cục bộ thay vì trong %APPDATA%\Claude\logs, ngay cả khi Claude Desktop được cài đặt từ bản tải xuống của chính nó: trong %LOCALAPPDATA%\Packages\, ở thư mục có tên bắt đầu bằng Claude_, tại LocalCache\Local\Claude\logs. Các tệp ở đó bao gồm mcp.log và mcp-server-Aggrega.log, tệp thứ hai chứa những gì máy chủ Aggrega ghi ra luồng lỗi chuẩn của nó. Một dòng chứa Using MCP server command: nêu lệnh mà ứng dụng đã khởi chạy, được lấy từ thiết lập Path to the aggrega executable của gói. Khi thiết lập nêu một đường dẫn mà tại đó không có gì, nhật ký chứa thông báo của trình thông dịch lệnh Windows rằng đường dẫn không được nhận diện là một lệnh, rồi báo rằng máy chủ không thể khởi động. Khi thư mục workspace không tồn tại — bị đổi tên, bị di chuyển hoặc chưa từng được tạo — máy chủ vẫn khởi động và trả lời mọi yêu cầu mà trợ lý đưa ra trong workspace đó bằng lời từ chối của nó, nên trợ lý nhận lời từ chối làm câu trả lời cho yêu cầu của mình thay vì ứng dụng báo lỗi kết nối. Lời từ chối nêu AGGREGA_WORKSPACE_ROOT là biến mà thiết lập Workspace folder của gói đặt, và trích dẫn thư mục đúng như ứng dụng đã truyền vào; mcp-server-Aggrega.log cũng chứa cùng lời từ chối đó. Một Workspace folder để trống cũng được trả lời theo cùng cách, bằng lời từ chối ở bước 3 nêu thiết lập đang trống, và nhật ký cũng chứa lời từ chối này. Hãy sửa thiết lập và khởi động lại ứng dụng như ở bước 4.
Cài đặt trình kết nối của Claude Desktop là con đường còn lại, dành cho máy chủ được truy cập qua HTTPS: xem Máy chủ được truy cập qua HTTPS.
Khi client không nhận toàn bộ tập công cụ
Aggrega công bố toàn bộ tập công cụ của nó và để client quyết định đưa bao nhiêu trong số đó tới mô hình. Một số client giới hạn số công cụ chúng đăng ký cùng lúc và bỏ phần còn lại. Khi điều đó xảy ra, mcp.announce_tools rút gọn những gì máy chủ công bố xuống các công cụ mà bạn nêu tên — xem Thu hẹp những gì máy chủ công bố.
Máy chủ được truy cập qua HTTPS
Mọi mục ở trên đều tự khởi chạy máy chủ. Một máy chủ do người khác chạy — một tiến trình chạy lâu dài trên một host, phục vụ một workspace — thì được truy cập qua mạng, và mục của nó nêu một địa chỉ thay vì một lệnh:
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}Đường dẫn luôn là /mcp; host là bất cứ địa chỉ nào người vận hành đã công bố cho máy chủ đó. Hãy hỏi họ. Gemini CLI nhận địa chỉ dưới httpUrl thay vì url: nó hiểu url là một máy chủ dùng transport event-stream cũ hơn, và httpUrl là một máy chủ dùng transport streamable HTTP, chính là transport mà máy chủ này sử dụng.
Client của bạn lấy token, không phải bạn. Không có gì về việc đăng nhập được cấu hình trong mục: máy chủ trả lời một yêu cầu chưa xác thực bằng cách nêu tài liệu cho biết máy chủ ủy quyền nào cấp token của nó, và một client hỗ trợ luồng ủy quyền của giao thức sẽ đọc tài liệu đó, đưa bạn đi đăng nhập, và đính kèm token nhận được vào mọi yêu cầu sau đó. Tên các scope mà nó có thể yêu cầu được công bố trong cùng tài liệu đó. Một client không triển khai luồng này không thể truy cập máy chủ loại này, và không có gì bạn thêm vào mục có thể thay thế cho nó.
Một công cụ mà các scope đăng nhập của bạn không với tới vẫn có trong danh sách công cụ. Lệnh gọi tới nó bị từ chối, kèm tên scope sẽ cho phép nó, và một client triển khai cơ chế step-up của giao thức sẽ đáp lại lời từ chối đó bằng cách yêu cầu bạn đăng nhập lại cho scope đó. Một client không hỗ trợ step-up vẫn có thể được cấp các scope ghi: người quản lý máy chủ ủy quyền đặt chúng làm scope mặc định cho client đó, để lần đăng nhập đầu tiên của nó đã mang chúng — với cái giá là mọi lần đăng nhập qua client đó từ đó trở đi đều mang quyền ghi. Những gì một bên gọi có thể tiếp cận trình bày mỗi scope cho phép gì, và thiết lập đó hoạt động thế nào đối với client tự đăng ký lại mỗi lần kết nối.
Những gì một server như vậy yêu cầu, và những gì người vận hành nó cấu hình, được trình bày trong aggrega mcp: tài liệu tham chiếu.
Xác minh kết nối
Sau khi client kết nối lại, hãy xác nhận rằng tích hợp đang hoạt động: client sẽ liệt kê các prompt soạn thảo của Aggrega (mỗi vai trò nhà phát triển, kiến trúc sư và vận hành một prompt, cộng một mẫu cho từng thực thể) và các công cụ soạn thảo — trong đó có scaffold, validate, describe và get-schema. Hãy yêu cầu trợ lý tạo bộ khung cho một thành phần, và nó sẽ trả về một bộ khung chứa các trường mà một Component yêu cầu. Nếu không có gì xuất hiện, hãy kiểm tra rằng aggrega version chạy được từ terminal và command của client trỏ tới tệp nhị phân — phần lưu ý về PATH ở trên đề cập nguyên nhân thường gặp.