MCP Server

Kết nối công cụ AI của bạn — Claude Code, Cursor, Codex, Claude Desktop, … — với Imbrace, và nó có thể làm việc trực tiếp với dữ liệu Imbrace của bạn: liệt kê board CRM, đọc hội thoại, xem lượt chạy workflow, v.v.

Bạn chỉ cần hai thứ:

• Một URL — gateway Imbrace host sẵn một server Model Context Protocol tại /mcp. Không phải cài hay chạy gì cả.
• Một API key — gửi dưới dạng Bearer token. Agent chỉ thấy đúng những gì tổ chức và vai trò của bạn cho phép, không hơn.

Bước 1 — Lấy API key

Tạo external token trong Imbrace Dashboard (xem Lấy API Key). Key có dạng api_....

Bước 2 — Kết nối công cụ của bạn

Chọn công cụ bên dưới và dán config. Ví dụ dùng gateway sandbox — thay host bằng gateway môi trường của bạn.

Claude Code

Một lệnh duy nhất:

claude mcp add --transport http imbrace "https://app-gateway.sandbox.imbrace.co/mcp" \
  --header "Authorization: Bearer api_xxx..."

Cursor

Thêm vào .cursor/mcp.json trong project — hoặc ~/.cursor/mcp.json để dùng ở mọi nơi:

{
  "mcpServers": {
    "imbrace": {
      "url": "https://app-gateway.sandbox.imbrace.co/mcp",
      "headers": { "Authorization": "Bearer api_xxx..." }
    }
  }
}

Codex CLI

Thêm vào ~/.codex/config.toml (bản Codex mới có hỗ trợ HTTP MCP):

[mcp_servers.imbrace]
url = "https://app-gateway.sandbox.imbrace.co/mcp"
bearer_token = "api_xxx..."

Với bản Codex cũ chưa hỗ trợ HTTP, bắc cầu qua mcp-remote:

[mcp_servers.imbrace]
command = "npx"
args = ["-y", "mcp-remote", "https://app-gateway.sandbox.imbrace.co/mcp", "--header", "Authorization: Bearer api_xxx..."]

Claude Desktop

Claude Desktop chỉ khởi chạy server local, nên bắc cầu URL qua mcp-remote. Vào Settings → Developer → Edit Config, thêm vào claude_desktop_config.json:

{
  "mcpServers": {
    "imbrace": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://app-gateway.sandbox.imbrace.co/mcp",
        "--header", "Authorization: Bearer api_xxx..."
      ]
    }
  }
}

Client khác

Mọi MCP client nhận URL kèm header đều dùng dạng chuẩn:

{
  "mcpServers": {
    "imbrace": {
      "url": "https://app-gateway.sandbox.imbrace.co/mcp",
      "headers": { "Authorization": "Bearer api_xxx..." }
    }
  }
}

Nếu client chỉ hỗ trợ server local (stdio), bắc cầu bằng:

npx -y mcp-remote "https://app-gateway.sandbox.imbrace.co/mcp" \
  --header "Authorization: Bearer api_xxx..."

Bước 3 — Thử ngay

Hỏi agent của bạn, ví dụ “Liệt kê các board Imbrace của tôi” hoặc “Xem các hội thoại mới nhất”. Nó sẽ tự chọn các tool như listBoards, listConversations, listFlows.

Mặc định chỉ đọc

Mặc định agent chỉ được xem chứ không được sửa — chỉ các tool đọc được mở. Muốn thêm quyền, thêm query parameter vào URL đã cấu hình:

Thêm vào URL	Tác dụng
?allowWrite=1	Agent được thêm quyền tạo và sửa dữ liệu
?allowDestructive=1	Agent được thêm quyền xóa dữ liệu (bao hàm write)
?services=dataBoard,workflow	Thu hẹp: chỉ các service này
?tags=boards,records	Thu hẹp: chỉ các chủ đề này

Ví dụ — chỉ data board, có quyền ghi:

https://app-gateway.sandbox.imbrace.co/mcp?services=dataBoard&allowWrite=1

Service: dataBoard, channel, platform, marketplace, workflow. Agent gọi tool chưa được bật sẽ nhận lỗi rõ ràng — không có gì thất bại âm thầm.

Cách hoạt động

Mỗi lần gọi tool được phát lại qua chính các route API của gateway với token của bạn, nên phạm vi tổ chức, quyền hạn và kiểm tra license áp dụng đúng như khi bạn tự gọi API. Tool chính là bộ operation agent-tools được tuyển chọn, cùng nguồn với bề mặt client.api của SDK. Endpoint là JSON-RPC stateless qua HTTP POST — không phải quản lý session.

Không dùng MCP? OpenAPI hợp nhất

Nền tảng dùng spec OpenAPI thay vì MCP (ví dụ Open WebUI) có thể trỏ vào GET /agent-tools/openapi.json với cùng header Authorization: agent-tools của tất cả service gộp thành một spec, cùng bộ lọc ?services= / ?tags= — một tool server thay vì năm. Executor tự ghép base URL với path của operation (request thành /agent-tools/<op-path>) cũng được chấp nhận: gateway bỏ prefix và phát lại request với thông tin xác thực của bạn.

Lựa chọn local — CLI

Muốn một stdio server chạy local (credential lấy từ profile CLI, không cấu hình URL)? CLI có sẵn cùng bộ registry tool: imbrace mcp.