← Danh mục tài liệu · raw markdown

Sổ tay kết nối Claude với hệ thống VIETAL

Tài liệu này dành cho người vận hành (nối Claude vào hệ thống) và dành cho Claude (biết mình được

làm gì, làm thế nào cho đúng). Cập nhật: 25/10/2026.

MụcĐịa chỉ
Trang cấp token + cấu hình sẵnhttps://dv.badt.vn/project/claude
API gốchttps://dv.badt.vn/project/api/v1
Tệp MCP serverhttps://dv.badt.vn/project/docs/tool/vietal_mcp.py
Danh mục tài liệu công khaihttps://dv.badt.vn/project/docs

---

1. Claude làm được gì (và bị chặn gì)

NhómClaude làm đượcGhi chú an toàn
ĐọcCây công việc, chi tiết việc, chỉ số, ngân sách, sự kiện, minh chứng, tài liệu đề ánKhông cần quyền ghi
Làm việcGiữ việc (lease), cập nhật tiến độ, nộp kết quả, ghi nhật kýNộp kết quả chỉ chuyển việc sang chờ duyệt
Cập nhật dữ liệuTạo việc/việc con, sửa hạn/địa điểm/sản phẩm, ghi khoản chi, thêm sự kiện, ghi chỉ sốMọi thay đổi có nhật ký kèm tên agent
Tiếp nhận văn bảnPhân tích biên bản/email/báo cáo thành kế hoạch thay đổi (chưa ghi), duyệt ghi, hoàn tácMặc định là chạy thử
Trao đổiHỏi quản trị viên, trả lời yêu cầuNội dung tự do sinh thêm sự kiện audit

Claude không làm được (cố ý): xoá dữ liệu; tự duyệt kết quả của chính mình; cấp/thu quyền cho agent khác;

đọc mật khẩu hay khoá API của hệ thống; đọc tệp ngoài thư mục minh chứng.

---

2. Ba cách để Claude làm việc

CáchPhù hợpĐọc tài liệu dự ánGhi dữ liệu
A. MCP server (vietal_mcp.py)Claude Code, Claude Desktop✅✅
B. Bash + curlClaude Code khi cần kiểm tra tay✅✅
C. Web fetch (claude.ai)chỉ đọc tài liệu công khai⚠️ chỉ tài liệu kỹ thuật❌

Khuyến nghị: A cho công việc thường ngày, B khi debug, C chỉ để đọc hướng dẫn.

---

3. Chuẩn bị (5 phút)

1. Token: /claude → «Cấp token cho Claude» → sao chép vtk_… (chỉ hiện một lần, hiệu lực 1–365 ngày).

Hoặc bằng CLI trên máy chủ:

   cd /var/www/html/dv.badt.vn/vietal_project
   sudo -u www-data php bin/token.php --agent=claude --label="Claude Desktop - may A" --days=180
   

2. Python: python3 --version (3.9+). MCP server chỉ dùng thư viện chuẩn, không cần pip install.

3. Tệp MCP: tải vietal_mcp.py ở /docs/tool/vietal_mcp.py, lưu tại ~/vietal_mcp.py

(Windows: C:\Users\<tên>\vietal_mcp.py).

4. Kiểm tra mạng: curl -s https://dv.badt.vn/project/api/v1/ping → {"ok":true,...}.

---

4. Cách A — MCP server (khuyến nghị)

4.1 Claude Code

claude mcp add vietal \
  --env VIETAL_TOKEN=vtk_xxx \
  --env VIETAL_BASE=https://dv.badt.vn/project/api/v1 \
  --env VIETAL_PROJECT=VIETAL-2026 \
  -- python3 ~/vietal_mcp.py

claude mcp list        # vietal: connected

Trong phiên làm việc gõ /mcp để xem 28 công cụ. Có thể đặt .mcp.json trong thư mục dự án để cả nhóm dùng chung:

{
  "mcpServers": {
    "vietal": {
      "command": "python3",
      "args": ["/duong/dan/vietal_mcp.py"],
      "env": { "VIETAL_TOKEN": "vtk_xxx", "VIETAL_PROJECT": "VIETAL-2026" }
    }
  }
}

4.2 Claude Desktop

Hệ điều hànhĐường dẫn tệp
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "vietal": {
      "command": "python3",
      "args": ["/Users/ten/vietal_mcp.py"],
      "env": {
        "VIETAL_TOKEN": "vtk_xxx",
        "VIETAL_BASE": "https://dv.badt.vn/project/api/v1",
        "VIETAL_PROJECT": "VIETAL-2026"
      }
    }
  }
}

Thoát hẳn ứng dụng (Cmd+Q / Quit ở khay hệ thống) rồi mở lại; biểu tượng công cụ trong ô chat là dấu hiệu đã nối.

4.3 Biến môi trường

BiếnBắt buộcÝ nghĩa
VIETAL_TOKENcóToken vtk_…
VIETAL_BASEkhôngMặc định https://dv.badt.vn/project/api/v1
VIETAL_PROJECTkhôngMặc định VIETAL-2026

---

5. 28 công cụ

5.1 Đọc và nắm tình hình

Công cụTham số chínhTrả về
vietal_workspaceprojectViệc nên làm, yêu cầu mở, job, nguồn lực, quy trình
vietal_task_treestatus, work_type, flag (overdue/leaf/branch/nodate), q, sortCả cây việc lồng nhau
vietal_list_tasksstatus, limitDanh sách phẳng
vietal_task_contexttask_id (id hoặc mã việc, vd A1.1, M4)Việc + chỉ số + minh chứng + sự kiện + nhật ký
vietal_search_documentsquery, limitTài liệu khớp từ khoá
vietal_read_documentdocument_id, refreshNội dung đã bóc chữ
vietal_list_tech_docs—Danh mục tài liệu kỹ thuật
vietal_read_tech_docslugNội dung tài liệu (agent-workspace, agent-claude, openapi, de-an, thiet-ke)
vietal_list_intakestatus, limitCác lần tiếp nhận gần đây
vietal_list_requestsstatus, directionYêu cầu/hỏi đáp
vietal_list_resources—Nguồn lực AI nội bộ
vietal_check_resourcecodeTình trạng một nguồn lực

5.2 Làm việc và cập nhật

Công cụTham số chính
vietal_claim_tasktask_id, ttl_minutes (mặc định 120, tối đa 1440), note
vietal_release_tasktask_id
vietal_update_progresstask_id, progress, status, message
vietal_update_tasktask_id, status, progress, due_date, start_date, location, deliverables, note, est_cost
vietal_create_tasktitle, parent (mã A1.1 hoặc id), work_type, description, deliverables, location, start_date, due_date, est_cost, currency, status, progress, priority, tags
vietal_submit_deliverabletask_id, title, content (Markdown), summary, kind
vietal_upload_evidencetask_id, path (tệp trên máy chạy MCP), title, kind, description
vietal_add_costtask_id, amount, currency, kind (income/expense/commitment), date, description, category, ref_no
vietal_add_eventtitle, date, time, kind (meeting/training/report/other), location, participants, notes
vietal_update_indicatorcode, value, note
vietal_logmessage, action, task_id

5.3 Trao đổi và tiếp nhận văn bản

Công cụTham số chính
vietal_asktitle, body, kind (question/blocker/request/review), priority, task_id
vietal_answer_requestrequest_id, answer, status (answered/closed)
vietal_intaketext, apply (mặc định false), force
vietal_intake_applyintake_id
vietal_intake_revertintake_id

---

6. Quy trình làm việc chuẩn

6.1 Nhận việc → làm → nộp

vietal_workspace                       → việc nên làm hôm nay
vietal_task_context {task_id}          → yêu cầu, chỉ số, minh chứng, sự kiện
vietal_claim_task {task_id}            → giữ việc, nhận claim_token + hạn
vietal_search_documents / read_document → đọc tài liệu liên quan
vietal_update_progress {task_id, progress: 60, message: "..."}
vietal_submit_deliverable {task_id, title, content}
vietal_release_task {task_id}

Không làm việc đã có agent khác giữ (API trả 409 already_claimed). Hết lease thì việc tự mở lại.

6.2 Tiếp nhận văn bản (biên bản họp, email, báo cáo)

vietal_intake {text: "<văn bản thô>"}     → preview.changes + warnings, KHÔNG ghi
   ↳ có chỗ mơ hồ → vietal_ask để hỏi người
   ↳ người đồng ý → vietal_intake_apply {intake_id}
   ↳ ghi sai      → vietal_intake_revert {intake_id}

Mỗi phần tử trong preview.changes có kind, action (insert/update/skip), title, before, after,

reason. Mục skip là những gì hệ thống từ chối ghi (thiếu trích dẫn nguyên văn, mã không tồn tại,

trùng lặp) — không ghi lại bằng tay, hãy báo người dùng.

6.3 Chẻ nhánh công việc và ghi tài chính

vietal_create_task {title: "Lập hồ sơ kỹ thuật", parent: "A1.1", work_type: "document",
                    deliverables: "Hồ sơ + dự toán", due_date: "2026-11-15"}
vietal_create_task {title: "Gửi CHU Angers thẩm định", parent: "A1.1.1", due_date: "2026-11-20"}
vietal_add_cost {task_id: <id>, amount: 1200, currency: "EUR", date: "2026-10-20",
                 description: "Đặt cọc khảo sát hạ tầng", ref_no: "HD-2026-014"}

Mã việc do hệ thống sinh (A1.1.3, A1.1.3.1). Tiến độ việc cha = trung bình việc con — đừng ghi đè.

6.4 Báo cáo tuần từ dữ liệu thật

1. vietal_task_tree {status: "doing"}      → việc đang làm
2. vietal_task_tree {flag: "overdue"}      → việc quá hạn
3. vietal_list_intake {limit: 20}          → văn bản mới tiếp nhận
4. vietal_list_requests {status: "open"}   → việc đang chờ người trả lời
5. soạn báo cáo: việc xong / đang làm / quá hạn / rủi ro / đề xuất
6. vietal_submit_deliverable gắn vào việc báo cáo tuần

Số liệu phải lấy từ công cụ; thiếu thì ghi «chưa có dữ liệu», không suy đoán.

6.5 Trả lời yêu cầu

vietal_list_requests {status: "open", direction: "to_agent"}
vietal_answer_request {request_id: 12, answer: "Đã có bản dịch Pháp, xem minh chứng #45."}

---

6bis. MCP thứ hai — kho ca bệnh và bộ giả lập

Ngoài MCP dự án (vietal_mcp.py), có MCP bệnh nhân ảo (vp_mcp.py) cho Claude làm việc với hai ứng dụng:

Ứng dụngViệc làm được
Patient Manager pnt.badt.vn/admin/patient_manager.phpĐọc, kiểm tra, chuẩn hoá, lưu, lưu trữ hồ sơ ca bệnh JSON; đọc/ghi prompt hệ thống của bộ giả lập
Bệnh nhân giả lập dv.badt.vn/ai/virtualpatientDanh sách ca, xem ca, chạy thử câu hỏi để nghe bệnh nhân trả lời, xem dữ liệu lâm sàng, đọc lại hội thoại phiên

Tệp và địa chỉ

Biến môi trường

BiếnDùng cho
PM_USERTài khoản portal pnt.badt.vn (bắt buộc cho pm_*)
PM_PASSMật khẩu portal
VP_COOKIEVIRTUALPATIENT_SESSION=… cho vp_* (ứng dụng 245 đăng nhập qua SSO nên cần cookie)

Giá trị thật không đặt trong tài liệu công khai — lấy ở trang /claude sau khi đăng nhập, hoặc do

quản trị viên cung cấp. Không dán mật khẩu/cookie vào chat, email, ảnh chụp màn hình.

Cấu hình Claude Desktop

{
  "mcpServers": {
    "benhnhan": {
      "command": "python3",
      "args": ["/duong/dan/vp_mcp.py"],
      "env": { "PM_USER": "…", "PM_PASS": "…", "VP_COOKIE": "VIRTUALPATIENT_SESSION=…" }
    }
  }
}

Dùng bằng dòng lệnh (Claude Code gọi bash)

python3 vp_cli.py status
python3 vp_cli.py list -q th276
python3 vp_cli.py ask th276 "Bác sốt mấy ngày rồi ạ?"
python3 vp_cli.py clinical th276
python3 vp_cli.py cases -n 20
python3 vp_cli.py case bn001 --summary
python3 vp_cli.py validate ca-moi.json && python3 vp_cli.py save bn301 ca-moi.json

Lấy cookie khi hết hạn (3 bước): mở trình duyệt → đăng nhập ứng dụng bệnh nhân giả lập →

DevTools → Application/Storage → Cookies → dv.badt.vn → sao chép VIRTUALPATIENT_SESSION.

Cookie hết hạn thì vp_* trả http_401.

Ghi chú kỹ thuật: chat bằng chữ đi POST /process_chat.php (field query); các endpoint

process_simulation*.php bắt buộc có audio_file. Câu hỏi dưới 4 từ và dưới 20 ký tự bị chặn (KEYWORD_QUERY).

7. Cách Claude đọc nội dung tài liệu (bóc chữ tự động)

Loại tệpCách bócGhi chú
.md .txt .csv .jsonđọc thẳngluôn có
.pdf có lớp textpdftotext -layoutnhanh, giữ bố cục
.pdf scanrender vài trang đầu → OCR10–60 s
.docx .xlsx .pptxđọc XML bên trongkhông cần Office
ảnh jpg/png/webpOCRảnh mờ có thể rỗng

Quy trình: vietal_search_documents → vietal_read_document (xem method, chars); nếu empty thì

refresh: true; vẫn rỗng thì tải bản gốc GET /evidence/{id}/file và đọc trực tiếp bằng vision.

Luôn ghi nguồn: document_id + tiêu đề khi trích dẫn số liệu.

---

8. Ngôn ngữ

---

9. Nguyên tắc bắt buộc

1. Không bịa số. Mọi con số lấy từ công cụ hoặc tài liệu đã đọc, nêu rõ nguồn.

2. Giữ việc trước khi làm, trả việc khi xong.

3. Không sửa dữ liệu của agent khác; quyền đóng việc (done) thuộc quản trị viên.

4. Thiếu dữ liệu thì hỏi (vital_ask → vietal_ask), không suy đoán.

5. Ghi dấu vết: mỗi lần nộp kèm vietal_log (đã làm gì, mất bao lâu).

6. Giới hạn: 120 yêu cầu/phút/token; tệp ≤ 25 MB; lease ≤ 24 giờ.

---

10. Mã lỗi và cách xử lý

Mã / HTTPNghĩaXử lý
missing_tokenChưa đặt VIETAL_TOKENSửa env trong cấu hình MCP, khởi động lại
invalid_token / expired_token (401)Token sai, hết hạn, bị thu hồiCấp token mới ở /claude
forbidden (403)Token thiếu quyền ghiDùng token scope read,write
429 rate_limitedQuá 120 yêu cầu/phútChờ rồi thử lại
409 already_claimedViệc đang do agent khác giữChọn việc khác hoặc chờ hết lease
409 not_ownerKhông phải chủ leaseChỉ chủ lease được trả việc/nộp
404 task_not_foundSai id/mã việcvietal_task_tree lấy id đúng
422 missing_projectTạo việc gốc mà không nêu dự ánThêm project
duplicate: trueVăn bản đã tiếp nhận trước đóMở bản ghi cũ, hoặc gửi force: true
apply_failedBản ghi không ở trạng thái chờ ghiPhân tích lại rồi mới ghi

Lỗi không tự xử lý được: gọi vietal_ask với kind: "blocker", kèm mã lỗi và thao tác vừa làm.

---

11. Cách B — Claude Code dùng bash + curl

export VIETAL_TOKEN='vtk_xxx'
B=https://dv.badt.vn/project/api/v1

curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/workspace" | jq '.workspace.tasks[:5]'
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/tasks?tree=1" | jq '.tree[0]'
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/documents?q=biên bản&limit=10" | jq '.documents[] | {id,title,has_text}'
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/documents/12" | jq -r '.text' | less
curl -s -X POST -H "Authorization: Bearer $VIETAL_TOKEN" -H 'Content-Type: application/json' \
     -d '{"ttl_minutes":120,"note":"Claude nhận việc"}' "$B/tasks/7/claim"
curl -s -X POST -H "Authorization: Bearer $VIETAL_TOKEN" -H 'Content-Type: application/json' \
     -d '{"progress":60,"message":"Đã đọc 12/20 tài liệu"}' "$B/tasks/7/progress"
curl -s -X POST -H "Authorization: Bearer $VIETAL_TOKEN" -H 'Content-Type: application/json' \
     -d '{"title":"Báo cáo rà soát","kind":"report","content":"# Kết quả\n..."}' "$B/tasks/7/deliverable"

Kiểm tra MCP server bằng tay:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' \
  | VIETAL_TOKEN=$VIETAL_TOKEN python3 ~/vietal_mcp.py | head -2

---

12. Cách C — Claude trên web

claude.ai không gửi được header Authorization, nên chỉ đọc tài liệu công khai:

Muốn ghi dữ liệu: dùng Claude Code/Desktop (A), hoặc nhờ quản trị viên dán văn bản vào /intake.

---

13. Prompt hệ thống gợi ý (dán vào Project Instructions)

Bạn là Claude, trợ lý thực thi của dự án VIETAL (CHU d'Angers – UPNT, chương trình RHIS/Expertise France).
Bạn nối với hệ thống qua MCP server "vietal" (28 công cụ, tiền tố vietal_).

Quy trình mặc định:
  vietal_workspace → chọn việc → vietal_claim_task → vietal_task_context
  → vietal_task_tree / vietal_search_documents / vietal_read_document
  → làm việc → vietal_update_progress → vietal_submit_deliverable → vietal_release_task.

Khi nhận văn bản thô (biên bản họp, email, báo cáo): gọi vietal_intake (chưa ghi),
trình bày từng thay đổi kèm chỗ còn mơ hồ; chỉ gọi vietal_intake_apply khi người dùng đồng ý.

Nguyên tắc: không bịa số; trích nguồn bằng document_id hoặc mã việc; thiếu dữ liệu thì vietal_ask;
không sửa dữ liệu của agent khác; trả lời cùng ngôn ngữ với người dùng.

---

13bis. Kiểm thử khói bằng một lệnh

VIETAL_TOKEN=vtk_xxx python3 tools/mcp_smoke.py          # chỉ đọc, 9 lời gọi
VIETAL_TOKEN=vtk_xxx python3 tools/mcp_smoke.py --write  # đọc + ghi, 21 lời gọi, in mã bản ghi để dọn

Script bắt tay JSON-RPC đúng như Claude Code/Desktop, in OK/LỖI từng công cụ và tổng kết n/N lời gọi thành công.

Chạy --write sẽ tạo việc/chi phí/sự kiện/yêu cầu/bản tiếp nhận thử — nhớ dọn theo mã in ra ở cuối.

Ghi chú: mọi công cụ nhận task_id dạng số hoặc mã việc ("M4", "A1.1.2"). Mã sai sẽ trả

isError: true kèm danh sách gợi ý, không âm thầm ghi nhầm.

14. Kiểm thử nhanh (không cần Claude)

TOKEN=vtk_xxx
BASE=https://dv.badt.vn/project/api/v1

curl -s "$BASE/ping"
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspace" | head -40
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/tasks?tree=1&flag=overdue" | head -30
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{"text":"Họp 25/10: hoàn thành A1.1, chi 200 EUR in ấn.","apply":false}' "$BASE/intake"

---

15. Bảo mật và vòng đời token

---

16. Câu hỏi thường gặp

Claude không thấy công cụ. claude mcp list xem trạng thái; chạy tay

VIETAL_TOKEN=… python3 ~/vietal_mcp.py để đọc lỗi trên stderr.

Windows báo không tìm thấy python3. Dùng "command": "python" hoặc đường dẫn đầy đủ

C:\\Python312\\python.exe.

Đường dẫn trong JSON Desktop. Dùng đường dẫn tuyệt đối, dấu / hoặc \\, không dùng ~.

Claude nói «chưa ghi gì». Đúng thiết kế: vietal_intake chỉ xem trước; gọi vietal_intake_apply.

Muốn Claude tự ghi luôn. Gọi vietal_intake với apply: true (khuyến nghị vẫn để người duyệt).

Có phải mở cổng trên máy chủ không. Không. Claude gọi ra https://dv.badt.vn/project/api/v1 (443);

MCP chạy cục bộ trên máy bạn bằng Python.

---

17. Tài liệu liên quan