Trợ lý AI

Kết nối trợ lý AI

Trợ lý AI của bạn (Claude Code, Codex, Claude Desktop…) đọc được số liệu tuyển dụng của công ty để trả lời câu hỏi và lập báo cáo. Khoá API chỉ nằm trên máy bạn, không bao giờ đi qua khung chat.

Cần chuẩn bị

  • Một khoá API dạng tk_live_… do admin tạo ở Cài đặt → Tích hợp → API & dữ liệu. Mỗi trợ lý một khoá, để thu hồi riêng được.
  • Gói trả phí. Báo cáo AI Agent (API dữ liệu) không có ở gói Free — khoá của công ty đang ở gói Free bị từ chối (lỗi 403).
  • Trợ lý chỉ đọc được, và không thấy thông tin cá nhân ứng viên (tên, email, số điện thoại, lương…) — chỉ có mã hồ sơ và số liệu.

Cách nhanh nhất: 3 bước

Dành cho trợ lý chạy trên máy tính của bạn và chạy được lệnh: Claude Code, Codex CLI, Cursor, Windsurf… Làm một lần, những lần sau chỉ việc hỏi.

  1. Lưu khoá vào máy. Mở PowerShell (Windows) hoặc Terminal (macOS/Linux), dán lệnh dưới đây, bấm Enter, rồi dán khoá khi được hỏi (khoá không hiện ra màn hình). Lệnh lưu khoá vào biến môi trường TICKUP_API_KEY trong tài khoản máy tính của bạn.
$k = Read-Host "Paste your Tick Up API key (tk_live_...)" -AsSecureString; $v = [Net.NetworkCredential]::new("", $k).Password.Trim(); if ($v -like "tk_live_*") { [Environment]::SetEnvironmentVariable("TICKUP_API_KEY", $v, "User"); "Saved. Close and reopen your terminal / AI assistant." } else { "Not a Tick Up key (tk_live_...). Nothing saved." }; Remove-Variable k, v
  1. Mở lại trợ lý AI (đóng hẳn cửa sổ terminal hoặc ứng dụng rồi mở lại) để trợ lý nhìn thấy khoá vừa lưu.
  2. Dán lời nhắc dưới đây vào trợ lý. Trợ lý tự cài kết nối Tick Up (MCP) và dùng khoá có sẵn trên máy — không hỏi khoá qua chat.
shell
Kết nối với dữ liệu tuyển dụng Tick Up của công ty tôi. Khoá API đã có sẵn trên máy này trong biến môi trường TICKUP_API_KEY.
Quy tắc: không hỏi khoá, không in khoá ra, không ghi khoá vào file hay vào code.
1. Nếu bạn là Claude Code: chạy đúng lệnh sau, rồi nhắc tôi mở lại Claude Code và gõ /mcp để kiểm tra:
   claude mcp add --transport http --scope user tickup https://api.tickup.vn/api/v1/mcp --header 'Authorization: Bearer ${TICKUP_API_KEY}'
   Nếu bạn là Codex CLI: chạy đúng lệnh sau, rồi nhắc tôi mở lại Codex:
   codex mcp add tickup --url https://api.tickup.vn/api/v1/mcp --bearer-token-env-var TICKUP_API_KEY
2. Nếu không cài được MCP: đọc hướng dẫn https://api.tickup.vn/api/v1/data/agent-guide rồi gọi API với header Authorization: Bearer lấy từ biến môi trường TICKUP_API_KEY.
3. Cuối cùng cho tôi biết công ty đang có bao nhiêu vị trí đang tuyển.

Tự cài MCP

MCP (Model Context Protocol) là chuẩn chung để trợ lý AI gọi công cụ bên ngoài. Tick Up có một máy chủ MCP chỉ đọc tại https://api.tickup.vn/api/v1/mcp, dùng chính khoá API làm chìa. Các lệnh dưới đây giả định bạn đã làm Bước 1 ở trên (khoá nằm trong biến TICKUP_API_KEY).

Claude Code

Chạy trong PowerShell hoặc Terminal (không dùng cmd). Dấu nháy đơn giữ nguyên tên biến TICKUP_API_KEY trong lệnh: Claude Code đọc khoá từ máy mỗi lần kết nối, khoá không bị chép vào file cấu hình.

shell
claude mcp add --transport http --scope user tickup https://api.tickup.vn/api/v1/mcp --header 'Authorization: Bearer ${TICKUP_API_KEY}'

Mở lại Claude Code, gõ /mcp: thấy tickup ở trạng thái đã kết nối là xong. Lần đầu trợ lý gọi một công cụ Tick Up, chọn Yes, and don't ask again để không bị hỏi lại.

Codex CLI

Codex đọc khoá từ biến môi trường mỗi lần chạy:

shell
codex mcp add tickup --url https://api.tickup.vn/api/v1/mcp --bearer-token-env-var TICKUP_API_KEY

Claude Desktop và claude.ai

Cách 1 — Connector (nếu thấy mục Request headers): Customize → Connectors → Add custom connector → URL https://api.tickup.vn/api/v1/mcp, Authentication chọn No sign-in, Request headers: authorization = Bearer tk_live_…. Khoá được Claude cất trong phần cài đặt kết nối (không nằm trong chat). Mục Request headers đang thử nghiệm, mới một số tổ chức có.

Cách 2 — File cấu hình Claude Desktop (cần cài Node.js): Settings → Developer → Edit Config, thêm khối dưới đây, thay tk_live_… bằng khoá, lưu lại rồi mở lại Claude Desktop. Khoá nằm trong file cấu hình trên máy bạn — giữ file này như mật khẩu.

claude_desktop_config.json
{
  "mcpServers": {
    "tickup": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote@0.14.3", "https://api.tickup.vn/api/v1/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer tk_live_…" }
    }
  }
}

Trợ lý khác (Cursor, VS Code, Windsurf, Gemini CLI…): thêm máy chủ MCP kiểu HTTP (Streamable HTTP) với URL ở trên và header Authorization: Bearer + khoá. Nếu ứng dụng cho đọc từ biến môi trường, dùng TICKUP_API_KEY.

Hỏi thử

Hỏi bằng tiếng Việt như hỏi một đồng nghiệp:

  • Tháng này công ty nhận bao nhiêu hồ sơ, tuyển được bao nhiêu người, so với tháng trước thế nào?
  • Trong 3 tháng qua, nguồn ứng viên nào hiệu quả nhất (tỷ lệ tuyển theo nguồn)?
  • Vị trí nào đang có hồ sơ nằm lâu nhất ở một bước mà chưa ai xử lý?
  • Tuần rồi bao nhiêu ứng viên vào vòng phỏng vấn, chia theo phòng ban?

ChatGPT và claude.ai trên web

ChatGPT (thử nghiệm): không cần khoá API — bạn đăng nhập Tick Up ngay trong ChatGPT. Chỉ Admin hoặc Member của công ty gói trả phí kết nối được. Cần tài khoản ChatGPT có quyền thêm kết nối MCP tuỳ chỉnh (gói trả phí; ở gói Business/Enterprise, admin ChatGPT của công ty có thể phải bật quyền này).

  1. Trên ChatGPT web, mở mục Plugins → Add → Add custom MCP server.
  2. Đặt tên Tick Up, ô Server URL dán https://api.tickup.vn/api/v1/mcp, phần Authentication chọn OAuth, rồi tạo.
  3. Bấm cài / kết nối: ChatGPT mở trang Tick Up → đăng nhập như bình thường (Google hoặc email) → đọc kỹ rồi bấm Đồng ý.
  4. Trong khung chat, chọn Tick Up (gõ @) rồi hỏi như các câu mẫu ở trên.

Hướng dẫn từng bước cho HR, kèm cách xử lý khi kết nối không hoàn tất: Hỏi số liệu tuyển dụng bằng ChatGPT (trung tâm hỗ trợ).

  • claude.ai: dùng Cách 1 ở trên nếu tổ chức của bạn đã có mục Request headers; nếu chưa, chờ bản đăng nhập OAuth.

An toàn và giới hạn

  • Chỉ đọc. Không công cụ nào sửa, xoá hay gửi gì trong Tick Up.
  • Thu hồi là ngắt ngay. Thu hồi khoá ở Cài đặt → API & dữ liệu, trợ lý mất quyền ở lần gọi kế tiếp (lỗi 401).
  • Chung giới hạn với Data API: mỗi khoá 120 lần/phút và 5.000 lần/ngày; riêng get_metrics 20 lần/phút, 500 lần/ngày.
  • Có nhật ký. Mỗi lần gọi được ghi lại (khoá nào, công cụ nào, bộ lọc nào) — không ghi dữ liệu trả về, không ghi khoá.
  • Không có thông tin cá nhân ứng viên — dữ liệu giống hệt Data API.

Thông tin kỹ thuật

Máy chủ MCP theo chuẩn Streamable HTTP, trả JSON (không SSE), không giữ phiên. Hỗ trợ giao thức 2025-03-26, 2025-06-18, 2025-11-25 (bắt tay initialize) và 2026-07-28. Xác thực bằng header Authorization: Bearer tk_live_…; khoá đặt trong URL bị từ chối (api_key_in_url). Mỗi công cụ trả đúng dữ liệu của route Data API tương ứng.

Công cụTương đươngDùng để
list_jobs/data/jobsTin tuyển dụng kèm các bước quy trình
list_applications/data/applicationsHồ sơ ứng tuyển (một ứng viên × một vị trí) — cùng luật đếm với màn Báo cáo
list_stage_transitions/data/stage-transitionsLịch sử chuyển bước / đổi trạng thái
list_candidates/data/candidatesThuộc tính nghề nghiệp của hồ sơ, không có thông tin cá nhân
list_interviews/data/interviewsLịch phỏng vấn, kết quả, điểm
list_evaluations/data/evaluationsPhiếu đánh giá (điểm, không có nhận xét chữ)
list_offers/data/offersThư mời nhận việc, mọi phiên bản (không có lương)
get_metrics/data/metricsBộ số của màn Báo cáo cho một kỳ, kèm kỳ trước để so sánh
get_catalog/data/catalogDanh mục gắn nhãn: quy trình, nguồn, lý do loại, thành viên, phòng ban
get_data_guide/data/agent-guideTừ điển dữ liệu + định nghĩa chỉ số cho trợ lý đọc trước khi tính