Chìa agent, nối Claude Code và các agent khác với KaleraPA

Cập nhật lần cuối: 03/11/202613 phút đọc

Chìa agent cho một coding agent, Claude Code là cái đầu tiên, nói chuyện trực tiếp với KaleraPA trong lúc nó đang làm việc: báo tiến độ, hỏi ý bạn khi gặp quyết định cần người, và nhận câu trả lời ngay cả khi phiên làm việc đó đã đóng kết nối rồi mở lại.

Tạo chìa ở đâu

Vô Cài đặt → Siêu Trợ Lý → Chìa agent, bấm Tạo chìa mới, đặt một tên gợi nhớ (ví dụ "Claude Code trên MacBook"). Chìa chỉ hiện đúng một lần lúc tạo, nhớ chép lại liền.

Mỗi chìa đang dùng phải có tên riêng: đặt trùng tên một chìa đã có (không phân biệt chữ hoa, chữ thường hay dấu) thì KaleraPA nhắc bạn đặt tên khác, để lúc giao việc trợ lý gọi đúng agent. Danh sách chìa ghi thêm dòng Đã làm trong dự án cho biết mỗi chìa đã làm trong những dự án nào.

Cài cho từng ứng dụng

Ngay sau khi tạo chìa ở Cài đặt → Siêu Trợ Lý → Chìa agent, KaleraPA hiện phần hướng dẫn: chọn đúng tên trong ô Agent bạn đang dùng, rồi bấm Chép đoạn cấu hình, đoạn chép ra đã có sẵn địa chỉ và chìa. Chìa chỉ hiện một lần nên cứ chép liền; sau này muốn coi lại thì mở Hướng dẫn kết nối ở danh sách chìa, chỗ chìa khi đó là <chìa-của-bạn>. Tên các mục dưới đây giống tên trong ô chọn và nằm theo đúng thứ tự trong ô đó. Nếu tự gõ theo bài này thì thay <chìa-của-bạn> bằng chìa đã chép. Ứng dụng nào cũng nối tới cùng một địa chỉ, https://pa.kalera.ai/api/v1/agents/mcp, và gửi chìa trong header Authorization: Bearer <chìa-của-bạn>.

Mấy điều chung:

  • File cấu hình đã có server khác thì gộp khối kalera vô chỗ đã có, đừng ghi đè cả file.
  • Chìa nằm trong file cấu hình, nên đừng để file đó trong thư mục dự án bạn đưa lên git.
  • Sửa file xong thì mở lại ứng dụng, hoặc bấm làm mới danh sách MCP, cho nó đọc lại.
  • Mục nào có "(mcp-remote)" trong tên thì cần cài Node.js, vì ứng dụng đó chưa tự gửi header được.

Claude Code

Chạy trong terminal, ở thư mục dự án (thêm --scope user để dùng cho mọi dự án), rồi gõ /mcp trong Claude Code để coi đã nối chưa.

claude mcp add --transport http kalera https://pa.kalera.ai/api/v1/agents/mcp --header "Authorization: Bearer <chìa-của-bạn>"

Tài liệu: https://code.claude.com/docs/en/mcp

Amp

Thêm khóa này vô ~/.config/amp/settings.json, nằm trong cặp ngoặc nhọn ngoài cùng cạnh các khóa amp.* khác, rồi chạy amp mcp list để coi.

"amp.mcpServers": {
  "kalera": { "url": "https://pa.kalera.ai/api/v1/agents/mcp", "headers": { "Authorization": "Bearer <chìa-của-bạn>" } }
}

Tài liệu: https://ampcode.com/docs/customize/mcp

Antigravity

Bấm dấu ... ở khung agent, chọn MCP Servers > Manage MCP Servers > View raw config (bản CLI thì sửa thẳng ~/.gemini/config/mcp_config.json), gộp khối này vô rồi bấm làm mới.

{
  "mcpServers": {
    "kalera": {
      "serverUrl": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://antigravity.google/docs/mcp

Auggie CLI (Augment)

Chạy trong terminal, rồi gõ /mcp trong auggie. Chỉ áp dụng cho Auggie CLI; extension Augment trong VS Code hay JetBrains chưa có chỗ điền header.

auggie mcp add kalera --transport http --url https://pa.kalera.ai/api/v1/agents/mcp -H "Authorization: Bearer <chìa-của-bạn>"

Tài liệu: https://docs.augmentcode.com/cli/integrations

Claude Desktop (mcp-remote)

Cần cài Node.js trước. Vô Settings > Developer > Edit Config của Claude Desktop, gộp khối này vô mcpServers, rồi thoát hẳn Claude Desktop và mở lại. Sau dấu hai chấm của header cố ý không có dấu cách: khoảng trắng nằm trong biến KALERA_AUTH để Windows không cắt sai.

{
  "mcpServers": {
    "kalera": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://pa.kalera.ai/api/v1/agents/mcp", "--transport", "http-only", "--header", "Authorization:${KALERA_AUTH}"],
      "env": { "KALERA_AUTH": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://github.com/geelen/mcp-remote#custom-headers

Claude Desktop / claude.ai (connector)

Vô Customize > Connectors, bấm Add custom connector, điền như dưới rồi bấm Add. Giá trị header phải có chữ Bearer và một dấu cách. Mục Request headers đang thử nghiệm và chỉ hiện với một số tổ chức; không thấy mục đó thì dùng mục "Claude Desktop (mcp-remote)" trong bài này.

Connector name: KaleraPA
Server URL: https://pa.kalera.ai/api/v1/agents/mcp
Authentication: No sign-in
Request headers: authorization = Bearer <chìa-của-bạn>

Tài liệu: https://claude.com/docs/connectors/custom/add-unlisted

Cline

Bấm biểu tượng MCP Servers của Cline, qua tab Configure, bấm Configure MCP Servers, gộp khối này vô rồi lưu. Giữ đúng "type": "streamableHttp": thiếu dòng đó Cline nối kiểu cũ và báo lỗi.

{
  "mcpServers": {
    "kalera": {
      "type": "streamableHttp",
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://docs.cline.bot/mcp/configuring-mcp-servers

Codex / ChatGPT desktop

Thêm vô cuối ~/.codex/config.toml (chưa có thì tạo), rồi mở lại Codex gõ /mcp để coi. Một file này dùng chung cho Codex CLI, extension Codex trong IDE và ứng dụng ChatGPT trên máy tính.

[mcp_servers.kalera]
url = "https://pa.kalera.ai/api/v1/agents/mcp"
http_headers = { Authorization = "Bearer <chìa-của-bạn>" }

Tài liệu: https://developers.openai.com/codex/mcp

Continue

Tạo file .continue/mcpServers/kalera.yaml ở gốc dự án (đừng đưa file này lên git). MCP của Continue chỉ chạy ở chế độ Agent.

name: KaleraPA
version: 0.0.1
schema: v1
mcpServers:
  - name: KaleraPA
    type: streamable-http
    url: https://pa.kalera.ai/api/v1/agents/mcp
    requestOptions:
      headers:
        Authorization: "Bearer <chìa-của-bạn>"

Tài liệu: https://docs.continue.dev/customize/deep-dives/mcp

Cursor

Gộp vô ~/.cursor/mcp.json (chưa có thì tạo), rồi coi Cursor Settings > MCP thấy kalera đèn xanh chưa. Cursor CLI đọc chung file này.

{
  "mcpServers": {
    "kalera": {
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://cursor.com/docs/context/mcp

Gemini CLI

Chạy trong terminal, rồi mở gemini gõ /mcp để coi. Giữ --scope user để dùng ở mọi thư mục.

gemini mcp add --scope user --transport http kalera https://pa.kalera.ai/api/v1/agents/mcp -H "Authorization: Bearer <chìa-của-bạn>"

Tài liệu: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

GitHub Copilot CLI

Chạy trong terminal, rồi mở copilot gõ /mcp để coi.

copilot mcp add --transport http --header "Authorization: Bearer <chìa-của-bạn>" kalera https://pa.kalera.ai/api/v1/agents/mcp

Tài liệu: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers

JetBrains AI Assistant (mcp-remote)

Cần cài Node.js trước. Vô Settings > Tools > AI Assistant > Model Context Protocol (MCP), bấm Add, chọn Command (stdio), dán khối này, chọn phạm vi Global rồi bấm OK. IDE báo không thấy npx thì thay "npx" bằng đường dẫn đầy đủ (lệnh which npx).

{
  "mcpServers": {
    "kalera": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://pa.kalera.ai/api/v1/agents/mcp", "--transport", "http-only", "--header", "Authorization:${KALERA_AUTH}"],
      "env": { "KALERA_AUTH": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://www.jetbrains.com/help/ai-assistant/mcp.html

Junie (JetBrains)

Gộp vô ~/.junie/mcp/mcp.json (dùng chung cho Junie trong IDE và Junie CLI), rồi gõ /mcp trong Junie để coi.

{
  "mcpServers": {
    "kalera": {
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://junie.jetbrains.com/docs/junie-cli-mcp-configuration.html

Kilo Code

Thêm vô ~/.config/kilo/kilo.jsonc, dưới khóa mcp (không phải mcpServers), rồi coi Settings > Agent Behaviour > MCP Servers.

{
  "mcp": {
    "kalera": {
      "type": "remote",
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" },
      "enabled": true
    }
  }
}

Tài liệu: https://kilo.ai/docs/automate/mcp/using-in-kilo-code

Kiro

Gộp vô ~/.kiro/settings/mcp.json, rồi coi panel MCP Servers của Kiro báo Active chưa.

{
  "mcpServers": {
    "kalera": {
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://kiro.dev/docs/mcp/configuration/

OpenCode

Gộp vô ~/.config/opencode/opencode.json, dưới khóa mcp, rồi chạy opencode mcp list để coi.

{
  "mcp": {
    "kalera": {
      "type": "remote",
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" },
      "enabled": true
    }
  }
}

Tài liệu: https://opencode.ai/docs/mcp-servers/

Qwen Code

Chạy trong terminal, rồi mở qwen gõ /mcp để coi.

qwen mcp add --scope user --transport http kalera https://pa.kalera.ai/api/v1/agents/mcp --header "Authorization: Bearer <chìa-của-bạn>"

Tài liệu: https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/

Roo Code

Bấm biểu tượng MCP của Roo Code, chọn Edit Global MCP, gộp khối này vô rồi lưu. Ghi đúng "type": "streamable-http" (khác Cline). Để chìa ở cấu hình Global, đừng để trong .roo/mcp.json của dự án.

{
  "mcpServers": {
    "kalera": {
      "type": "streamable-http",
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://docs.roocode.com/features/mcp/using-mcp-in-roo

VS Code (GitHub Copilot)

Chạy trong terminal trên macOS hay Linux (cần lệnh code trong PATH), rồi mở Command Palette gõ MCP: List Servers để coi. Trên Windows thì mở MCP: Open User Configuration và gộp khối tương ứng dưới khóa servers.

code --add-mcp '{"name":"kalera","type":"http","url":"https://pa.kalera.ai/api/v1/agents/mcp","headers":{"Authorization":"Bearer <chìa-của-bạn>"}}'

Tài liệu: https://code.visualstudio.com/docs/copilot/reference/mcp-configuration

Warp

Vô Settings > Agents > MCP servers, bấm Add, dán khối này rồi lưu; bấm Start nếu kalera chưa tự chạy.

{
  "mcpServers": {
    "kalera": {
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://docs.warp.dev/agents/capabilities/mcp/

Windsurf (Devin Desktop)

Trong khung Cascade mở menu MCP, chọn Open MCP config file (đúng file Cascade đọc), gộp khối này vô rồi bấm làm mới.

{
  "mcpServers": {
    "kalera": {
      "serverUrl": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://docs.windsurf.com/plugins/cascade/mcp

Zed

Chạy action zed: open settings file, gộp khối này vô rồi lưu, chờ chấm xanh ở Settings > AI > MCP Servers.

{
  "context_servers": {
    "kalera": {
      "url": "https://pa.kalera.ai/api/v1/agents/mcp",
      "headers": { "Authorization": "Bearer <chìa-của-bạn>" }
    }
  }
}

Tài liệu: https://zed.dev/docs/ai/mcp

ChatGPT trên web chưa nối được: phần kết nối MCP của nó chỉ nhận đăng nhập kiểu OAuth, chưa nhận chìa.

Từ lúc cài xong, agent nói chuyện thẳng với KaleraPA qua bốn việc dưới đây.

Bốn việc agent làm được qua chìa

  • Báo việc: agent gửi một dòng tiến độ, ví dụ việc vừa xong hoặc một chỗ bị kẹt. KaleraPA ghi lại thành một tin nhắn trong một cuộc trò chuyện riêng cho agent đó. Câu KaleraPA trả lời một lần báo việc chỉ là lời xác nhận đã nhận: agent đừng chờ lệnh trong câu đó, việc mới luôn tới qua Nhận việc. Báo về một việc được giao thì agent gửi kèm mã việc (task_id), và báo cáo quay về đúng cuộc trò chuyện đã giao việc.
  • Nhận việc: agent gọi kalera_next_task lúc rảnh và sau mỗi lần báo việc, để lấy việc trợ lý giao cho nó (coi phần "Cho agent tự nhận việc" bên dưới và bài "Giao việc cho agent ngay trong chat").
  • Hỏi ý: agent gặp một quyết định cần người, nó hỏi thẳng. KaleraPA tự trả lời được thì trả lời liền; câu nào cần bạn quyết thì hiện thành thẻ, kèm thông báo trên điện thoại hoặc máy tính, bạn trả lời trên web hay mobile đều được.
  • Chờ trả lời: agent giữ kết nối chờ câu trả lời, kể cả khi phiên làm việc của nó đã đổi sang một máy chủ khác lúc chờ.

Cho agent tự nhận việc

Agent chỉ thấy việc trợ lý giao khi nó gọi kalera_next_task. Mỗi lần gọi, agent chờ tối đa khoảng 55 giây: có việc thì nhận nội dung việc kèm mã việc, không có thì gọi lại để nghe tiếp. Gọi kèm project là tên thư mục đang làm thì agent chỉ nhận việc của đúng dự án đó, hoặc việc không gắn dự án nào. Sau 30 phút không có việc nào, KaleraPA trả về stop_listening để agent ngừng nghe cho khỏi tốn; muốn nghe lại thì đợi vài phút rồi chạy lại đoạn lệnh dưới đây.

Để agent tự nhận việc, mở agent trong thư mục dự án rồi dán đoạn lệnh này:

Lặp lại: gọi kalera_next_task (project = tên thư mục này). Có việc thì làm, xong gọi kalera_report kèm task_id và level done. Không có việc thì gọi lại. Khi nhận stop_listening thì dừng.

Không làm xong được thì agent gọi kalera_report với level blocked, việc đó chuyển sang Chưa xong. Coi agent có đang nghe hay không ở dòng Lần nhận việc gần nhất của từng chìa trong Cài đặt → Siêu Trợ Lý → Chìa agent.

Thẻ câu hỏi trong cuộc trò chuyện

Câu nào agent hỏi mà cần bạn quyết thì hiện thành thẻ ngay dưới cuộc trò chuyện của agent đó, trên web lẫn ứng dụng di động.

  • Câu hỏi có lựa chọn: agent đưa sẵn vài lựa chọn (ví dụ "Thấy rồi" và "Chưa thấy") thì mỗi lựa chọn hiện thành một nút, bạn bấm một cái là trả lời xong. Muốn trả lời khác thì bấm Trả lời khác rồi gõ câu của mình. Agent nhận đúng chữ trên nút bạn bấm, hoặc đúng câu bạn gõ.
  • Câu hỏi mở: thẻ có ô để bạn gõ câu trả lời rồi bấm Gửi trả lời.
  • Câu đã xong thu gọn lại: câu đã có người trả lời, hay agent đã thôi chờ, chỉ còn một dòng ngắn ghi ai trả lời và trả lời gì. Bấm vô dòng đó để coi lại câu hỏi.
  • Ẩn câu đã xong: bấm Ẩn câu đã xong để dọn chỗ. Chỗ đó còn một dòng ghi bao nhiêu câu đang ẩn, bấm Hiện lại là coi lại được. Lựa chọn này nhớ riêng cho từng cuộc trò chuyện, trên đúng trình duyệt hay điện thoại bạn đang dùng. Câu còn chờ trả lời thì luôn hiện, không bao giờ bị ẩn.

Agent chưa biết gửi lựa chọn mà viết sẵn ở cuối câu hỏi theo kiểu "Chọn: Có / Không", hay "(A) ... (B) ..." ngay sau dấu chấm hỏi, thì KaleraPA tự tách ra thành nút. Khi KaleraPA chuyển câu hỏi tới bạn, nó cũng tự gắn các lựa chọn có sẵn trong câu hỏi.

Tin agent không bao giờ được coi là lời bạn

Mọi tin agent gửi vô đều được đánh dấu là nội dung từ bên ngoài, giống như một trang web hay một tệp đính kèm: agent không tự mở được công cụ nào đụng vô máy của bạn, và KaleraPA không bao giờ coi một dòng agent gửi là một câu bạn tự gõ, nên tin của agent không ghi được vô Lời dặn. Khi một tin báo việc cần xử lý, chính trợ lý quyết định làm gì. Nếu cuộc trò chuyện nhận tin thuộc một dự án (ví dụ tên dự án trùng với project agent báo), trợ lý làm được ngay trên thư mục dự án với đúng những quyền của lịch tự động trong dự án: chạy lệnh và theo dõi việc đang chạy, không mở trình duyệt, không điều khiển màn hình. Cuộc trò chuyện không thuộc dự án nào thì trợ lý không đụng tới máy.

Thu hồi chìa

Vẫn ở Cài đặt → Siêu Trợ Lý → Chìa agent, bấm Thu hồi ở chìa muốn khoá. Agent đang dùng chìa đó mất kết nối liền, phải tạo chìa mới rồi cài lại mới dùng tiếp được.

Một cửa sổ, một chìa

Nếu bạn chạy nhiều cửa sổ Claude Code song song trên cùng một máy, mỗi cửa sổ nên có một chìa riêng. Dùng chung một chìa cho nhiều cửa sổ làm tin nhắn của hai phiên lẫn vô cùng một cuộc trò chuyện, và hạn mức dùng cũng bị dồn chung.

Chìa agent, nối Claude Code và các agent khác với KaleraPA | KaleraPA