Chuyển đến nội dung

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ì

SkillDùng để
imbrace-get-startedLầ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-sdkTypeScript @imbrace/sdk và Python imbrace: khởi tạo client, namespace, xử lý lỗi
imbrace-mcpKế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-cliCài đặt, đăng nhập và viết script với CLI imbrace; chạy imbrace mcp trên máy
imbrace-build-agents-workflowsAI agent + chat streaming, workflow, knowledge hub, board CRM từ đầu đến cuối
imbrace-vibe-codeXâ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:

Terminal window
claude plugin marketplace add imbrace-co/imbrace-agent-toolkit
claude plugin install imbrace-developer@imbrace-developer-tools

Hoặc trong một phiên Claude Code:

/plugin marketplace add imbrace-co/imbrace-agent-toolkit
/plugin install imbrace-developer@imbrace-developer-tools

Cậ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ườngMCP URL
Production (server của plugin)https://app-gatewayv2.imbrace.co/mcp
Sandboxhttps://app-gateway.sandbox.imbrace.co/mcp
On-premisehttps://<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):

Terminal window
claude mcp add --transport http imbrace-sandbox https://app-gateway.sandbox.imbrace.co/mcp
claude mcp add --transport http imbrace-onprem https://<your gateway>/mcp

Sau đó /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:

  1. Trong Claude Code, chạy /mcp, chọn imbrace rồi chọn Authenticate.
  2. Đăng nhập iMBrace trên trình duyệt vừa mở.
  3. Ở màn hình đồng ý (consent), chọn tổ chức mà kết nối này làm việc.
  4. 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.
  5. 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

ScopeCho phép
imbrace.readTool đọc. Luôn được cấp.
imbrace.writeTool tạo và cập nhật
imbrace.deleteTool 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, ?allowWrite và ?allowDestructive trê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:

Terminal window
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:

Terminal window
claude mcp add --transport http imbrace https://app-gatewayv2.imbrace.co/mcp

Sau đó /mcp → imbrace → Authenticate. Với API key, dùng lệnh ở Dùng API key thay thế.

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.

  1. 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.
  2. Đặt tên theo môi trường, ví dụ iMBrace hoặc iMBrace (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.
  3. 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).
  4. 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ứngNguyên nhânCách xử lý
/mcp báo imbrace lỗi: Dynamic Client Registration rejected (HTTP 404) … Cannot POST /registerGateway đó chưa bật OAuth, nên không thể bắt đầu đăng nhậpTắt server imbrace của plugin và kết nối bằng API key
401 kèm invalid_tokenChư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 keyKey sai, hết hạn, thuộc môi trường khác, hoặc rỗngKiểm tra key và host của gateway
403Vai trò của bạn trong tổ chức đó thiếu quyềnLiê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 MCPNhờ 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 enabledOAuth: 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 đượcGateway chưa có OAuth, hoặc không truy cập được từ internetKiể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.