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ẵn | https://dv.badt.vn/project/claude |
| API gốc | https://dv.badt.vn/project/api/v1 |
| Tệp MCP server | https://dv.badt.vn/project/docs/tool/vietal_mcp.py |
| Danh mục tài liệu công khai | https://dv.badt.vn/project/docs |
---
| Nhóm | Claude làm được | Ghi chú an toàn |
|---|---|---|
| Đọc | Câ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 đề án | Không cần quyền ghi |
| Làm việc | Giữ 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ệu | Tạ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ản | Phâ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ác | Mặc định là chạy thử |
| Trao đổi | Hỏi quản trị viên, trả lời yêu cầu | Nộ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.
---
| Cách | Phù hợp | Đọc tài liệu dự án | Ghi dữ liệu |
|---|---|---|---|
A. MCP server (vietal_mcp.py) | Claude Code, Claude Desktop | ✅ | ✅ |
| B. Bash + curl | Claude 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.
---
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,...}.
---
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" }
}
}
}
| 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.
| Biến | Bắt buộc | Ý nghĩa |
|---|---|---|
VIETAL_TOKEN | có | Token vtk_… |
VIETAL_BASE | không | Mặc định https://dv.badt.vn/project/api/v1 |
VIETAL_PROJECT | không | Mặc định VIETAL-2026 |
---
| Công cụ | Tham số chính | Trả về |
|---|---|---|
vietal_workspace | project | Việc nên làm, yêu cầu mở, job, nguồn lực, quy trình |
vietal_task_tree | status, work_type, flag (overdue/leaf/branch/nodate), q, sort | Cả cây việc lồng nhau |
vietal_list_tasks | status, limit | Danh sách phẳng |
vietal_task_context | task_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_documents | query, limit | Tài liệu khớp từ khoá |
vietal_read_document | document_id, refresh | Nội dung đã bóc chữ |
vietal_list_tech_docs | — | Danh mục tài liệu kỹ thuật |
vietal_read_tech_doc | slug | Nội dung tài liệu (agent-workspace, agent-claude, openapi, de-an, thiet-ke) |
vietal_list_intake | status, limit | Các lần tiếp nhận gần đây |
vietal_list_requests | status, direction | Yêu cầu/hỏi đáp |
vietal_list_resources | — | Nguồn lực AI nội bộ |
vietal_check_resource | code | Tình trạng một nguồn lực |
| Công cụ | Tham số chính |
|---|---|
vietal_claim_task | task_id, ttl_minutes (mặc định 120, tối đa 1440), note |
vietal_release_task | task_id |
vietal_update_progress | task_id, progress, status, message |
vietal_update_task | task_id, status, progress, due_date, start_date, location, deliverables, note, est_cost |
vietal_create_task | title, 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_deliverable | task_id, title, content (Markdown), summary, kind |
vietal_upload_evidence | task_id, path (tệp trên máy chạy MCP), title, kind, description |
vietal_add_cost | task_id, amount, currency, kind (income/expense/commitment), date, description, category, ref_no |
vietal_add_event | title, date, time, kind (meeting/training/report/other), location, participants, notes |
vietal_update_indicator | code, value, note |
vietal_log | message, action, task_id |
| Công cụ | Tham số chính |
|---|---|
vietal_ask | title, body, kind (question/blocker/request/review), priority, task_id |
vietal_answer_request | request_id, answer, status (answered/closed) |
vietal_intake | text, apply (mặc định false), force |
vietal_intake_apply | intake_id |
vietal_intake_revert | intake_id |
---
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.
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.
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 đè.
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.
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."}
---
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ụng | Việ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/virtualpatient | Danh 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ỉ
https://dv.badt.vn/project/docs/tool/vp_mcp.py (19 công cụ, tiền tố pm_ và vp_)https://dv.badt.vn/project/docs/tool/vp_cli.pyhttps://dv.badt.vn/project/docs/mcp-benh-nhanhttps://dv.badt.vn/project/claude — cần đăng nhậpBiến môi trường
| Biến | Dùng cho |
|---|---|
PM_USER | Tài khoản portal pnt.badt.vn (bắt buộc cho pm_*) |
PM_PASS | Mật khẩu portal |
VP_COOKIE | VIRTUALPATIENT_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).
| Loại tệp | Cách bóc | Ghi chú |
|---|---|---|
.md .txt .csv .json | đọc thẳng | luôn có |
.pdf có lớp text | pdftotext -layout | nhanh, giữ bố cục |
.pdf scan | render vài trang đầu → OCR | 10–60 s |
.docx .xlsx .pptx | đọc XML bên trong | không cần Office |
ảnh jpg/png/webp | OCR | ả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.
---
---
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ờ.
---
| Mã / HTTP | Nghĩa | Xử lý |
|---|---|---|
missing_token | Chưa đặt VIETAL_TOKEN | Sử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ồi | Cấp token mới ở /claude |
forbidden (403) | Token thiếu quyền ghi | Dùng token scope read,write |
429 rate_limited | Quá 120 yêu cầu/phút | Chờ rồi thử lại |
409 already_claimed | Việc đang do agent khác giữ | Chọn việc khác hoặc chờ hết lease |
409 not_owner | Không phải chủ lease | Chỉ chủ lease được trả việc/nộp |
404 task_not_found | Sai id/mã việc | vietal_task_tree lấy id đúng |
422 missing_project | Tạo việc gốc mà không nêu dự án | Thêm project |
duplicate: true | Văn bản đã tiếp nhận trước đó | Mở bản ghi cũ, hoặc gửi force: true |
apply_failed | Bản ghi không ở trạng thái chờ ghi | Phâ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.
---
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
---
claude.ai không gửi được header Authorization, nên chỉ đọc tài liệu công khai:
https://dv.badt.vn/project/docshttps://dv.badt.vn/project/docs/agent-claude.md (bản thô của tài liệu này)https://dv.badt.vn/project/docs/agent-workspace.mdhttps://dv.badt.vn/project/docs/de-an.mdhttps://dv.badt.vn/project/docs/openapi.mdMuố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.
---
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.
---
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.
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"
---
sha256.php bin/token.php --revoke=<id>).---
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.
---
docs/AGENT_WORKSPACE.md — toàn bộ endpoint + quy trình agent từ xadocs/openapi.yaml — đặc tả máy đọcdocs/THIET_KE_HE_THONG.md — thiết kế hệ thống (gồm luồng tiếp nhận văn bản)docs/TOM_TAT_DE_AN.md — nội dung đề ánhttps://dv.badt.vn/project/claude — trang cấp token và cấu hình sẵn