Tích hợp Soluta qua MCP

Soluta là máy chủ MCP từ xa cho sổ kế toán doanh nghiệp Việt Nam (Thông tư 133 và 99). Soluta nhận kết nối từ Claude, ChatGPT và Grok/Cursor (đăng nhập OAuth). Kênh khác chưa mở. Trang này chỉ ghi điều đang chạy.

Endpoint

Mục	Giá trị
MCP	`https://mcp.soluta.vn/mcp`
Transport	Streamable HTTP
Giao thức	nên dùng `2025-06-18`; máy chủ cũng nhận `2024-11-05`, `2025-03-26`, `2025-11-25`, `2026-07-28`
Tài nguyên được bảo vệ	`https://mcp.soluta.vn/.well-known/oauth-protected-resource/mcp`
Máy chủ uỷ quyền	`https://auth.mcp.soluta.vn` · metadata `/.well-known/oauth-authorization-server`

Kết nối nhanh

Claude, ChatGPT và Grok/Cursor: làm theo hướng dẫn kết nối. Kênh khác chưa mở.

Xác thực (OAuth 2.1)

Gọi /mcp không có thẻ ⇒ 401 kèm WWW-Authenticate: Bearer resource_metadata="…/oauth-protected-resource/mcp", scope="soluta.so".
Đọc metadata tài nguyên ⇒ máy chủ uỷ quyền https://auth.mcp.soluta.vn ⇒ đọc /.well-known/oauth-authorization-server.
Đăng ký client: Client ID Metadata Document (client_id là URL https) hoặc DCR (POST /register). Client công khai: token_endpoint_auth_method = none.
Authorization code + PKCE S256 (bắt buộc). Scope soluta.so.
Redirect https khớp nguyên chuỗi với bản đăng ký.
Người dùng đăng nhập soluta.vn (email hoặc Google), chọn công ty, rồi bấm Cho phép. Màn đồng ý hiện tên miền redirect của bạn.
Access token có aud = https://mcp.soluta.vn/mcp và gắn đúng một sổ người dùng chọn (claim soluta_so). Muốn sổ khác ⇒ thêm một kết nối nữa.
Refresh token xoay vòng: mỗi lần đổi nhận refresh mới, refresh cũ hết dùng; dùng lại refresh cũ ⇒ cả chuỗi bị thu hồi. Hết hạn / thu hồi ⇒ invalid_grant.

Ghi sổ và duyệt

Công cụ chỉ soạn đề xuất (soluta_proposal_create…). Sổ không đổi cho tới khi người dùng duyệt.
Duyệt trong khung Soluta (MCP Apps ui://) ngay trong cuộc trò chuyện: người dùng xem bút toán, căn cứ, chứng từ rồi bấm Duyệt.
Hiện Soluta chỉ nhận kết nối từ Claude và ChatGPT; kênh khác chưa mở.

Tệp chứng từ

Máy chủ không nhận byte tệp. Gửi tham số content_base64 ⇒ kết quả lỗi KHONG_NHAN_TEP.
Client đọc hoá đơn / sao kê / bảng số dư tại máy, rồi gửi trường dữ liệu: soluta_einvoice_import ⇒ invoices, soluta_opening_draft ⇒ balances.

Công cụ

Danh sách có thể đổi giữa các bản phát hành — luôn đọc tools/list. Đây là tools/list mà client của bạn thấy (máy chủ 0.9.1263).

Tên	Tiêu đề	Loại
`soluta_books_open`	Open accounting books	Có tác động
`soluta_proposal_list`	List proposals	Chỉ đọc
`soluta_proposal_show`	Show proposal	Chỉ đọc
`soluta_proposal_create`	Propose journal entry	Có tác động
`soluta_balance`	Account balance	Chỉ đọc
`soluta_accounts`	Chart of accounts	Chỉ đọc
`soluta_parties`	Parties	Chỉ đọc
`soluta_trial_balance`	Trial balance	Chỉ đọc
`soluta_balance_sheet`	Balance sheet (B01)	Chỉ đọc
`soluta_income_statement`	Income statement (B02)	Chỉ đọc
`soluta_reconcile_bank`	Reconcile bank statement	Chỉ đọc
`soluta_party_propose`	Propose party	Có tác động
`soluta_company_propose`	Propose company profile	Có tác động
`soluta_vat_return`	VAT return (01/GTGT)	Chỉ đọc
`soluta_period_close_propose`	Propose period close	Có tác động
`soluta_company`	Company profile	Chỉ đọc
`soluta_einvoice_import`	Read e-invoice XML	Chỉ đọc
`soluta_worksheet_create`	Build worksheet	Chỉ đọc
`soluta_proposal_approve_in_chat`	Post to ledger	Ghi sổ · destructiveHint
`soluta_proposal_approve_from_ui`	Post from review card	Ghi sổ · destructiveHint
`soluta_proposal_reject_from_ui`	Reject from review card	Ghi sổ · destructiveHint
`soluta_opening_draft`	Draft opening balances	Chỉ đọc
`soluta_book_create`	Create new book	Có tác động
`soluta_law_search`	Search law	Chỉ đọc
`soluta_law_show`	Show law article	Chỉ đọc
`soluta_law_gap`	Report law gap	Có tác động
`soluta_feedback`	Send feedback to Soluta	Có tác động
`soluta_precedents`	Precedents	Chỉ đọc
`soluta_party_balances`	Party balances	Chỉ đọc
`soluta_ledger`	General ledger and journal	Chỉ đọc
`soluta_financial_report`	Financial report	Chỉ đọc
`soluta_report_export`	Export report file	Chỉ đọc
`soluta_review`	Review book	Chỉ đọc
`soluta_manage`	Management reports	Chỉ đọc
`soluta_tax`	Tax returns and deadlines	Chỉ đọc
`soluta_trace`	Trace entries and figures	Chỉ đọc
`soluta_correct`	Propose correction	Có tác động
`soluta_fixed_asset`	Draft depreciation	Có tác động
`soluta_prepaid`	Draft prepaid allocation	Chỉ đọc
`soluta_period_close_draft`	Draft closing entries	Chỉ đọc
`soluta_contractor_tax`	Draft foreign contractor tax	Chỉ đọc
`soluta_payroll`	Draft payroll	Chỉ đọc
`soluta_cit_return`	Draft corporate income tax	Chỉ đọc

Lỗi thường gặp

Gặp	Nghĩa	Làm gì
HTTP `401` + `WWW-Authenticate`	thiếu thẻ, thẻ sai hoặc hết hạn	làm OAuth theo `resource_metadata`; thẻ hết hạn thì dùng refresh token
HTTP `403` `DUONG_LECH_SO_CUA_TOKEN`	thẻ cấp cho sổ khác với sổ trong địa chỉ `/mcp/<mã sổ>`	dùng đúng thẻ của sổ ấy, hoặc gọi `/mcp`
kết quả lỗi `KHONG_NHAN_TEP`	đã gửi byte tệp	đọc tệp tại máy, gửi trường (xem «Tệp chứng từ»)
kết quả lỗi `QUA_TAI`	một lời gọi vượt trần tính toán	chia thành nhiều lời gọi nhỏ hơn
HTTP `429`	quá nhiều yêu cầu trong thời gian ngắn (giới hạn lượt)	chờ rồi thử lại, giãn nhịp gọi
`invalid_grant` ở `/token`	refresh token hết hạn, đã dùng hoặc bị thu hồi	cho người dùng kết nối lại

Liên hệ

Câu hỏi tích hợp, báo lỗi: info@soluta.vn.