Agent Toolkit
iMBrace Agent Toolkit là plugin chính thức của iMBrace cho các AI coding agent. Cài một lần, agent của bạn sẽ biết cách xây dựng trên iMBrace: SDK TypeScript/Python, MCP server được host sẵn, CLI, AI agent, workflow, knowledge hub và board CRM.
Plugin có tên iMBrace Developer, gồm hai dạng:
- Claude Code — sáu skill cùng với MCP server iMBrace được host sẵn, nên agent còn có thể đọc (và, nếu bạn cho phép, thay đổi) dữ liệu iMBrace của bạn.
- ChatGPT và Codex — cùng sáu skill đó, dưới dạng plugin chỉ có skill. Nó chỉ chứa hướng dẫn; không gọi dịch vụ nào và không giữ credential nào. Nếu muốn có tool, hãy tự kết nối MCP server (Các MCP client khác).
Mã nguồn và báo lỗi: github.com/imbrace-co/imbrace-agent-toolkit (MIT).
Toolkit gồm những gì
| Skill | Dùng để |
|---|---|
imbrace-get-started | Lần đầu dùng: chọn môi trường, lấy API key an toàn, thực hiện một lời gọi đã xác minh |
imbrace-sdk | TypeScript @imbrace/sdk và Python imbrace: khởi tạo client, namespace, xử lý lỗi |
imbrace-mcp | Kết nối MCP server được host sẵn trong mọi client; đăng nhập OAuth, API key làm phương án dự phòng |
imbrace-cli | Cài đặt, đăng nhập và viết script với CLI imbrace; chạy imbrace mcp trên máy |
imbrace-build-agents-workflows | AI agent + chat streaming, workflow, knowledge hub, board CRM từ đầu đến cuối |
imbrace-vibe-code | Xây dựng, deploy và host một ứng dụng hoàn chỉnh trên iMBrace (theo /skill.md) |
Skill tự được nạp khi yêu cầu của bạn khớp. Mở một phiên mới và hỏi, ví dụ: “Help me get started with iMBrace”.
Cài đặt trong Claude Code
Cần Claude Code 2.1.275 trở lên. Từ terminal:
claude plugin marketplace add imbrace-co/imbrace-agent-toolkitclaude plugin install imbrace-developer@imbrace-developer-toolsHoặc trong một phiên Claude Code:
/plugin marketplace add imbrace-co/imbrace-agent-toolkit/plugin install imbrace-developer@imbrace-developer-toolsCập nhật bằng claude plugin marketplace update imbrace-developer-tools; gỡ bằng claude plugin uninstall imbrace-developer.
Chọn môi trường
Plugin thêm MCP server với tên imbrace, không lưu credential nào trong plugin. Server này kết nối tới production; MCP URL của từng môi trường:
| Môi trường | MCP URL |
|---|---|
| Production (server của plugin) | https://app-gatewayv2.imbrace.co/mcp |
| Sandbox | https://app-gateway.sandbox.imbrace.co/mcp |
| On-premise | https://<gateway của bạn>/mcp |
Với môi trường khác, hãy tự thêm một server (bên dưới). Mỗi môi trường có tài khoản, tổ chức và API key riêng: hãy đăng nhập, hoặc tạo key, trong đúng môi trường bạn kết nối. Thêm ?services= hoặc ?tags= vào URL sẽ thu hẹp các tool được liệt kê và gọi được (xem MCP Server); đó là bộ lọc, không phải kiểm soát quyền truy cập.
Dùng nhiều môi trường
Server imbrace của plugin luôn trỏ tới production. Thêm mỗi môi trường khác dưới một tên riêng; mỗi server đăng nhập riêng (tắt server của plugin bằng /mcp nếu bạn chỉ muốn dùng môi trường kia):
claude mcp add --transport http imbrace-sandbox https://app-gateway.sandbox.imbrace.co/mcpclaude mcp add --transport http imbrace-onprem https://<your gateway>/mcpSau đó /mcp → từng server → Authenticate. Với gateway chưa có OAuth, hãy thêm --header "Authorization: Bearer $IMBRACE_SANDBOX_API_KEY" vào lệnh, mỗi môi trường một biến key. Tool được liệt kê theo từng server (ví dụ mcp__imbrace-sandbox__listBoards), nên khi hỏi hãy nói rõ bạn muốn môi trường nào.
ChatGPT và Codex
Cùng các skill này sẽ được phát hành trong thư mục plugin của OpenAI với tên iMBrace Developer; link sẽ được thêm vào README của toolkit khi phát hành. Gói này chỉ có skill: để Codex dùng được cả tool iMBrace, hãy thêm MCP server vào Codex như hướng dẫn ở Các MCP client khác.
Kết nối MCP server
Có hai cách đăng nhập, mỗi kết nối dùng một cách: OAuth (đăng nhập trên trình duyệt, không phải sao chép gì) và API key (api_...).
Đăng nhập bằng OAuth
Trên gateway đã bật OAuth:
- Trong Claude Code, chạy
/mcp, chọnimbracerồi chọn Authenticate. - Đăng nhập iMBrace trên trình duyệt vừa mở.
- Ở màn hình đồng ý (consent), chọn tổ chức mà kết nối này làm việc.
- Chọn quyền cấp: chỉ đọc, hoặc đọc + ghi (và xóa, nếu cần). Bạn có thể bỏ chọn ghi và xóa.
- Quay lại Claude Code, các tool sẽ xuất hiện. Thử “List my iMBrace boards” — agent sẽ gọi một tool như
listBoards.
Quyền bạn cấp
| Scope | Cho phép |
|---|---|
imbrace.read | Tool đọc. Luôn được cấp. |
imbrace.write | Tool tạo và cập nhật |
imbrace.delete | Tool xóa (bao gồm quyền ghi) |
- Tổ chức được cố định bởi lần cấp quyền. Mọi lời gọi chạy trong tổ chức bạn đã chọn ở màn hình đồng ý; tổ chức do client hoặc model gửi lên sẽ bị ghi đè. Muốn làm việc ở tổ chức khác, hãy đăng nhập lại.
- Quyền ghi và xóa chỉ đến từ các scope này. Với OAuth,
?allowWritevà?allowDestructivetrên URL bị bỏ qua. - Mỗi lời gọi tool được phát lại qua API thông thường dưới danh nghĩa của bạn, nên tư cách thành viên, quyền theo vai trò và license của bạn trong tổ chức đó vẫn được áp dụng.
Phiên, chuyển đổi và thu hồi
- Client tự lưu và làm mới token. Access token có hiệu lực 1 giờ và được gia hạn bằng refresh token, nên bạn không phải đăng nhập lại mỗi giờ.
- Đổi tổ chức hoặc quyền:
/mcp→imbrace→ clear authentication, rồi Authenticate lại và chọn lại. - Thu hồi: clear authentication trong client để xóa các token nó đã lưu. Access token không được đối chiếu với danh sách thu hồi, nên token đã cấp vẫn hợp lệ cho đến khi hết hạn (tối đa 1 giờ). Việc xóa một người khỏi tổ chức hoặc đổi vai trò của họ có hiệu lực ngay, vì gateway kiểm tra tư cách thành viên và vai trò ở mỗi lời gọi.
Dùng API key thay thế
Dùng API key khi gateway chưa bật OAuth, cho CI và máy không có giao diện, và cho client không hỗ trợ OAuth. Tạo key của tổ chức (api_...) trong iMBrace Portal tại GovernCore → Generate External Token (xem Lấy API Key), rồi tự đặt nó vào biến môi trường — đừng bao giờ dán key vào khung chat hay commit nó.
Trong Claude Code, thêm server bằng key, và tắt server imbrace của plugin (hoặc tắt plugin) nếu không muốn có hai mục:
claude mcp add --transport http imbrace https://app-gatewayv2.imbrace.co/mcp \ --header "Authorization: Bearer $IMBRACE_API_KEY"Kết nối bằng API key là chỉ đọc trừ khi URL có ?allowWrite=1 (tạo và cập nhật) hoặc ?allowDestructive=1 (thêm cả xóa). Header Authorization cố định sẽ tắt luồng OAuth của client, nên mỗi kết nối chỉ dùng một cách.
Các MCP client khác
Ví dụ dùng production; thay host bằng gateway của môi trường bạn. Cách OAuth chỉ áp dụng khi gateway đã bật OAuth.
OAuth:
claude mcp add --transport http imbrace https://app-gatewayv2.imbrace.co/mcpSau đó /mcp → imbrace → Authenticate. Với API key, dùng lệnh ở Dùng API key thay thế.
Trong .cursor/mcp.json (hoặc ~/.cursor/mcp.json cho mọi project). OAuth — sau đó Cursor sẽ đề nghị đăng nhập vào server:
{ "mcpServers": { "imbrace": { "url": "https://app-gatewayv2.imbrace.co/mcp" } }}API key:
{ "mcpServers": { "imbrace": { "url": "https://app-gatewayv2.imbrace.co/mcp", "headers": { "Authorization": "Bearer ${env:IMBRACE_API_KEY}" } } }}Trong ~/.codex/config.toml:
[mcp_servers.imbrace]url = "https://app-gatewayv2.imbrace.co/mcp"OAuth: chạy codex mcp login imbrace (với các phiên bản Codex có hỗ trợ MCP OAuth). API key: thay vào đó thêm bearer_token_env_var = "IMBRACE_API_KEY" dưới [mcp_servers.imbrace].
OAuth: thêm iMBrace dưới dạng custom connector — xem Claude trên web, desktop và mobile.
Với API key (chỉ Claude Desktop), bridge qua mcp-remote trong claude_desktop_config.json, như trên trang MCP Server.
Bridge URL bằng mcp-remote, công cụ này sẽ mở trình duyệt để đăng nhập (OAuth):
npx -y mcp-remote https://app-gatewayv2.imbrace.co/mcpAPI key:
npx -y mcp-remote https://app-gatewayv2.imbrace.co/mcp \ --header "Authorization: Bearer $IMBRACE_API_KEY"Không dùng URL: CLI chạy một stdio server cục bộ từ profile đã lưu — imbrace mcp.
Claude trên web, desktop và mobile (custom connector)
Không dùng Claude Code? Hãy kết nối iMBrace với Claude — claude.ai, Claude Desktop và ứng dụng mobile — dưới dạng custom connector. Cách này cần gateway đã bật OAuth: custom connector không gửi được API key.
- Mở Settings → Connectors và chọn Add custom connector. Với gói Team hoặc Enterprise, Owner cần thêm connector trước trong phần cài đặt connector của tổ chức; sau đó thành viên kết nối từ cài đặt của mình.
- Đặt tên theo môi trường, ví dụ
iMBracehoặciMBrace (sandbox), rồi dán MCP URL từ Chọn môi trường. Để trống OAuth client ID và secret trong phần nâng cao: Claude tự đăng ký với iMBrace. - Chọn Connect, đăng nhập iMBrace, và ở màn hình đồng ý (consent) chọn tổ chức và quyền truy cập (đọc, ghi, xóa).
- Trong một cuộc trò chuyện, bật connector từ menu công cụ, rồi hỏi, ví dụ “List my iMBrace boards”.
- Mỗi môi trường và tổ chức một connector. Muốn đổi tổ chức hoặc quyền, hãy ngắt kết nối connector rồi kết nối lại.
- Gateway phải truy cập được từ internet. Claude kết nối từ cloud của Anthropic, không phải từ máy của bạn. Gateway on-premise nằm sau VPN hoặc firewall chỉ dùng được từ Claude Code, hoặc từ một client khác chạy trên máy truy cập được gateway đó.
- Connector thêm trên claude.ai cũng có trong Claude Desktop và ứng dụng mobile.
Xử lý sự cố
| Triệu chứng | Nguyên nhân | Cách xử lý |
|---|---|---|
/mcp báo imbrace lỗi: Dynamic Client Registration rejected (HTTP 404) … Cannot POST /register | Gateway đó chưa bật OAuth, nên không thể bắt đầu đăng nhập | Tắt server imbrace của plugin và kết nối bằng API key |
401 kèm invalid_token | Chưa đăng nhập, hoặc phiên đăng nhập đã hết hạn | /mcp → imbrace → clear authentication, rồi Authenticate lại |
401 khi dùng API key | Key sai, hết hạn, thuộc môi trường khác, hoặc rỗng | Kiểm tra key và host của gateway |
403 | Vai trò của bạn trong tổ chức đó thiếu quyền | Liên hệ admin của tổ chức |
402 plan_feature_unavailable (MCP access is not included in your plan) | Gói của tổ chức không bao gồm quyền dùng MCP | Nhờ admin iMBrace bật MCP access cho gói đó, hoặc Authenticate lại và chọn tổ chức có gói hỗ trợ MCP |
| Thiếu tool ghi hoặc xóa, hoặc lỗi tool not enabled | OAuth: lần cấp quyền thiếu imbrace.write / imbrace.delete. API key: URL thiếu ?allowWrite=1 / ?allowDestructive=1. Hoặc bộ lọc ?services= / ?tags= đã loại tool đó | Xác thực lại và cấp quyền ghi (hoặc xóa), hoặc sửa URL |
| Custom connector không kết nối được | Gateway chưa có OAuth, hoặc không truy cập được từ internet | Kiểm tra <gateway>/.well-known/oauth-protected-resource/mcp. Dùng gateway có OAuth, hoặc Claude Code với API key |
Hỗ trợ
Báo lỗi và đặt câu hỏi tại GitHub Issues của toolkit.
MCP server do iMBrace Limited vận hành. Các lời gọi chạy dưới danh nghĩa người dùng và tổ chức iMBrace bạn đăng nhập (hoặc bằng API key của bạn), theo chính sách quyền riêng tư và điều khoản của iMBrace. Các skill chỉ gợi ý lệnh và code; khi bạn chạy, chúng gọi các service của iMBrace (và npm hoặc PyPI để cài SDK và CLI), liệt kê ở mục Network and data trong README của plugin.