Hướng dẫn công cụ (tools)
Toàn bộ Tools của SSI MCP, làm được gì, cần cung cấp thông tin gì và cách hỏi để có kết quả tốt nhất.
Tools (công cụ) là năng lực cốt lõi của SSI MCP: mỗi Tool làm đúng 1 việc cụ thể (VD: tra giá cổ phiếu, lấy báo cáo tài chính) và lấy dữ liệu thật từ hệ thống SSI. Hiện có 54 tool đang hoạt động (Phase 1).
Bạn không cần nhớ tên tool
Chỉ cần hỏi tự nhiên bằng tiếng Việt. AI tự chọn đúng Tool, điền tham số, gọi dữ liệu SSI rồi trình bày lại bằng ngôn ngữ dễ hiểu. Bảng bên dưới giúp bạn biết SSI MCP trả lời được những gì và nên nêu rõ thông tin nào trong câu hỏi.
Tool hoạt động thế nào
- Bạn đặt câu hỏi trong khung chat (VD "Giá SSI hôm nay thế nào?").
- AI chọn Tool phù hợp và tự điền tham số (mã cổ phiếu, khoảng ngày...).
- SSI MCP kiểm tra quyền truy cập, gọi hệ thống dữ liệu SSI và trả kết quả về cho AI.
- AI tóm tắt kết quả cho bạn. Số liệu lấy nguyên từ Tool, AI không tự bịa số.
Tất cả Tool đều chỉ đọc dữ liệu (read-only), không ghi hay thay đổi bất cứ thứ gì. Dữ liệu tính theo múi giờ Việt Nam (UTC+7); đơn vị tiền là VND (trừ tỷ giá và chỉ số thế giới, tính theo đơn vị của thị trường gốc).
Mẹo hỏi để có kết quả tốt
- Nêu rõ mã cổ phiếu (VD SSI, VNM, VCB) thay vì "cổ phiếu ngân hàng đó".
- Nêu rõ khoảng thời gian (VD "từ 01/09/2026 đến 15/09/2026", "3 tháng gần nhất").
- Nêu rõ loại dữ liệu (VD "báo cáo kết quả kinh doanh quý", "tỷ lệ sở hữu khối ngoại").
- Hỏi từng chủ đề một, hoặc dùng Prompt dựng sẵn cho các nhu cầu phức tạp.
- Câu hỏi mơ hồ (VD "thị trường hôm nay") có thể khiến AI hỏi lại; bổ sung thông tin là được.
Quy ước chung của các tham số
| Tham số | Ý nghĩa và quy ước |
|---|---|
symbol | Mã cổ phiếu (VD SSI, VNM, VCB). |
fromDate, toDate (hoặc from, to) | Khoảng ngày, định dạng DD/MM/YYYY (VD 01/09/2026), không nhận dạng yyyy-mm-dd. Riêng marketdata_get_vn_index_performance dùng MM/yyyy. |
| Giới hạn khoảng ngày | Tối đa 730 ngày (~2 năm) cho mỗi lần hỏi ở các tool có khoảng ngày tự do. Vượt giới hạn, yêu cầu bị từ chối và AI sẽ gợi ý chia nhỏ khoảng ngày. Xem Resources. |
exchange | Sàn giao dịch: HOSE, HNX, UPCOM. |
language | Ngôn ngữ nội dung: VN hoặc EN. |
pageSize, pageIndex (hoặc pageNumber) | Phân trang cho danh sách dài: số dòng mỗi trang và trang thứ mấy. |
order, orderBy | Thứ tự sắp xếp: ASC (tăng dần) hoặc DESC (giảm dần), và cột dùng để sắp xếp. |
yearReport, lengthReport, isAudit | Báo cáo tài chính: năm báo cáo; kỳ báo cáo (1 đến 4 = quý, 5 = cả năm); 1 = đã kiểm toán, 0 = chưa. |
criteria | Tiêu chí xếp hạng của marketdata_list_top_stocks: topIncreaseByValue, topDecreaseByValue, topIncreaseByPercent, topDecreaseByPercent, topByVolume, topbytradingamount. |
latest | true để chỉ lấy dữ liệu mới nhất, thay cho fromDate/toDate. |
Cột Bắt buộc trong các bảng dưới là thông tin AI phải có mới gọi được Tool; nếu bạn chưa nêu, AI sẽ hỏi lại. Cột Tuỳ chọn dùng để lọc, sắp xếp, phân trang. Bạn không cần tự gõ tên tham số, chỉ cần mô tả bằng lời.
1. Cổ phiếu / Giá / Giao dịch
Giá trong phiên, giá theo ngày, thống kê giá, top tăng/giảm, biên độ giá, danh sách mã theo sàn.
Ví dụ hỏi: "Giá SSI hôm nay thế nào? Top 10 cổ phiếu tăng mạnh nhất sàn HOSE tuần này?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_get_stock_infor | Lấy dữ liệu giao dịch trong phiên (intraday) của cổ phiếu — bản đầy đủ, gồm phân trang liên tục (sysToken) và giá gốc chưa điều chỉnh (Raw) | symbol | fromDate, toDate, sysToken |
marketdata_get_intraday_stock_infor | Lấy dữ liệu giao dịch trong phiên (intraday) của cổ phiếu | symbol | fromDate, toDate, latest |
marketdata_get_market_data_intraday_stock_infor | Lấy dữ liệu giao dịch trong phiên (intraday) của cổ phiếu — bản rút gọn chỉ gồm giá/khối lượng cơ bản (OHLCV), không có phân trang liên tục | symbol | fromDate, toDate, latest |
marketdata_get_stock_performance | Lấy biến động giá cổ phiếu theo ngày (thay đổi 1 ngày, % thay đổi, % thay đổi luỹ kế) | symbol, fromDate, toDate | — |
marketdata_get_stock_statistic_by_range | Lấy thống kê giá cổ phiếu theo khoảng thời gian (cao/thấp nhất, khối lượng, giá trị khớp lệnh bình quân) | symbol, fromDate, toDate | — |
marketdata_get_stock_statistic_by_range_1month | Lấy thống kê giá cổ phiếu 1 tháng gần nhất (cao/thấp nhất, khối lượng, giá trị khớp lệnh bình quân — fromDate/toDate do server tự tính, không nhận input) | symbol | — |
marketdata_list_stock_daily_data | Lấy dữ liệu giao dịch cổ phiếu theo ngày | symbol, fromDate, toDate | exchange, pageSize, pageIndex |
marketdata_list_daily_stock_infor | Lấy dữ liệu giao dịch cổ phiếu chi tiết theo ngày (bản đầy đủ, gồm khối ngoại/nội) | symbol, fromDate, toDate | exchange, pageSize, pageIndex |
marketdata_list_stock_statistics | Lấy thống kê chỉ số tài chính cổ phiếu — P/E, P/B, ROE, ROA, biến động giá | — | industryCode, symbol, exchange, language, pageIndex, pageSize |
marketdata_list_top_stocks | Lấy top cổ phiếu theo tiêu chí (tăng/giảm giá trị, tăng/giảm %, khối lượng, giá trị giao dịch) | criteria, exchange, fromDate, toDate | limit |
marketdata_list_symbol_on_top | Lấy danh sách mã chứng khoán dẫn đầu theo tiêu chí (tăng trưởng, thanh khoản...) | — | code |
marketdata_list_symbols_by_exchange | Lấy danh sách mã chứng khoán theo sàn | exchange | stockType |
marketdata_get_market_master_data | Lấy dữ liệu biên độ giá (trần/sàn/tham chiếu) toàn bộ mã trên thị trường trong ngày | — | — |
marketdata_list_adjusted_rate | Lấy danh sách tỷ lệ điều chỉnh giá do sự kiện doanh nghiệp, theo khoảng ngày | — | fromDate, toDate |
2. Chỉ số thị trường
VNINDEX, VN30, HNX30, chỉ số thế giới, % thay đổi VNINDEX theo tháng, chỉ số tài chính theo rổ chỉ số.
Ví dụ hỏi: "VNINDEX 6 tháng gần đây diễn biến ra sao?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_get_index_daily_data | Lấy dữ liệu chỉ số thị trường theo ngày (VNINDEX, VN30, HNX30...) | indexCode, from, to | includeToday |
marketdata_get_index_daily_data_6month | Lấy dữ liệu chỉ số thị trường 6 tháng gần nhất (VNINDEX, VN30, HNX30... — fromDate/toDate do server tự tính, không nhận input) | indexCode | includeToday |
marketdata_get_vn_index_performance | Lấy % thay đổi VNINDEX theo tháng (month-over-month, year-over-year) | fromDate, toDate | — |
marketdata_list_world_index | Lấy dữ liệu chỉ số thị trường thế giới theo ngày (KOSPI, SET.BK...) | — | worldIndexCode, fromDate, toDate, pageIndex, pageSize |
marketdata_list_ratio_index | Lấy chỉ số tài chính theo rổ chỉ số (VNINDEX, VNSML...) | — | id, fromDate, toDate, pageNumber, pageSize, indexName, dateType, order, orderBy |
3. Trái phiếu / Chứng quyền
Giao dịch và hồ sơ trái phiếu doanh nghiệp, thông tin và danh sách chứng quyền có đảm bảo (CW), giao dịch tự doanh CW.
Ví dụ hỏi: "Trái phiếu mã X đang giao dịch giá bao nhiêu?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_get_bond | Lấy dữ liệu giao dịch trái phiếu doanh nghiệp theo mã | bondCode | fromDate, toDate |
marketdata_get_corporate_bond_profile | Lấy hồ sơ trái phiếu doanh nghiệp theo mã | — | symbol, fromDate, toDate |
marketdata_get_covered_warrant_information | Lấy thông tin chi tiết 1 chứng quyền có đảm bảo (Covered Warrant) theo mã | — | symbol, fromDate, toDate |
marketdata_list_corporate_cw | Lấy danh sách chứng quyền có đảm bảo (Covered Warrant) đã phát hành | — | fromDate, toDate, pageIndex, pageSize, dateType |
marketdata_list_cw_proprietary_trading | Lấy dữ liệu giao dịch tự doanh chứng quyền (Covered Warrant) theo mã CW | fromDate, toDate | symbol, pageIndex, pageSize |
4. ETF / Quỹ đầu tư
iNAV quỹ ETF (mới nhất và theo thời gian), thông tin quỹ đầu tư.
Ví dụ hỏi: "iNAV mới nhất của quỹ E1VFVN30 là bao nhiêu?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_get_etf_inav_index_latest | Lấy iNAV (Indicative NAV) mới nhất của quỹ ETF theo mã | etfSymbol | — |
marketdata_get_etf_inav_chart | Lấy dữ liệu biểu đồ iNAV (Indicative NAV) của quỹ ETF theo thời gian | etfSymbol | fromDate, toDate |
marketdata_get_fund_information | Lấy thông tin quỹ đầu tư theo tên quỹ | fundName | — |
5. Hồ sơ doanh nghiệp / Cổ đông / Lãnh đạo
Hồ sơ công ty niêm yết, ban lãnh đạo, cổ đông lớn, cơ cấu sở hữu, lịch sử vốn hoá và cổ tức.
Ví dụ hỏi: "Ai đang lãnh đạo công ty SSI? Cổ đông lớn của VNM là ai?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_get_company_profile | Lấy hồ sơ công ty niêm yết | symbol | exchange, language, updateDate |
marketdata_list_company_leaderships | Lấy danh sách ban lãnh đạo công ty niêm yết | symbol | language, order, orderBy, pageSize, pageIndex |
marketdata_get_share_holder_summary | Lấy tổng hợp tỷ lệ sở hữu theo nhóm (nước ngoài/nhà nước/khác) của 1 mã cổ phiếu | symbol | — |
marketdata_list_share_holder_detail | Lấy danh sách cổ đông lớn theo mã cổ phiếu | symbol | language, order, orderBy, type, pageSize, pageIndex |
marketdata_get_latest_cap_and_dividend | Lấy lịch sử vốn hoá, tài sản và cổ tức tiền mặt của cổ phiếu theo năm | symbol | — |
6. Tài chính doanh nghiệp
Bảng cân đối kế toán, kết quả kinh doanh, lưu chuyển tiền tệ, chỉ số tài chính (P/E, P/B, ROE, ROA, EPS...). Các tool hậu tố _1year tự lấy 4 quý gần nhất, không cần nhập ngày.
Ví dụ hỏi: "Báo cáo kết quả kinh doanh 4 quý gần nhất của SSI? P/E, P/B của VNM?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_list_finance_balance_sheet | Lấy bảng cân đối kế toán (Balance Sheet) theo kỳ báo cáo | symbol | yearReport, lengthReport, from, to, isAudit, pageSize, pageNumber |
marketdata_list_finance_balance_sheet_1year | Lấy bảng cân đối kế toán 1 năm gần nhất (≈4 quý báo cáo gần nhất) theo mã cổ phiếu (from/to do server tự tính, không nhận input) | symbol | yearReport, lengthReport, isAudit, pageSize, pageNumber |
marketdata_list_finance_income_statement | Lấy báo cáo kết quả kinh doanh (Income Statement) theo kỳ báo cáo | symbol | yearReport, lengthReport, from, to, isAudit, pageSize, pageNumber |
marketdata_list_finance_income_statement_1year | Lấy báo cáo kết quả kinh doanh 1 năm gần nhất (≈4 quý báo cáo gần nhất) theo mã cổ phiếu (from/to do server tự tính, không nhận input) | symbol | yearReport, lengthReport, isAudit, pageSize, pageNumber |
marketdata_list_finance_cash_flow | Lấy báo cáo lưu chuyển tiền tệ (Cash Flow) theo kỳ báo cáo | symbol | yearReport, lengthReport, from, to, isAudit, pageSize, pageNumber |
marketdata_list_finance_cash_flow_1year | Lấy báo cáo lưu chuyển tiền tệ 1 năm gần nhất (≈4 quý báo cáo gần nhất) theo mã cổ phiếu (from/to do server tự tính, không nhận input) | symbol | yearReport, lengthReport, isAudit, pageSize, pageNumber |
marketdata_list_finance_indicator | Lấy chỉ số tài chính cổ phiếu theo kỳ báo cáo (P/E, P/B, ROE, ROA, EPS...) | symbol | yearReport, lengthReport, pageSize, pageIndex, orderBy, order |
marketdata_list_corp_finance_finance_indicator | Lấy chỉ số tài chính cổ phiếu — bản tóm tắt nhanh (lợi nhuận ròng, P/E, P/B theo kỳ báo cáo; xem marketdata_list_finance_indicator để có đầy đủ chỉ số ROE/ROA/EPS...) | symbols | — |
marketdata_list_fundamental_ratio_history | Lấy lịch sử chỉ số P/E, P/B theo mã cổ phiếu | symbol, fromDate, toDate | pageSize, pageIndex |
marketdata_get_fundamental_analysis_index | Lấy chỉ số phân tích cơ bản (Fundamental Analysis) của cổ phiếu theo thời gian | symbol | fromDate, toDate |
7. Tin tức / Sự kiện doanh nghiệp
Tin tức công ty (danh sách và chi tiết), sự kiện doanh nghiệp: chia cổ tức, họp ĐHCĐ, giao dịch nội bộ...
Ví dụ hỏi: "Có tin gì mới về công ty X không? Lịch chia cổ tức của SSI?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_list_company_news | Lấy tin tức công ty theo mã cổ phiếu | — | source, isWorldNews, symbol, from, to, orderBy, order, language, searchText, categoryCode, newsType, pageSize, pageIndex |
marketdata_list_company_news_1month | Lấy tin tức công ty 1 tháng gần nhất theo mã cổ phiếu (fromDate/toDate do server tự tính, không nhận input) | — | source, isWorldNews, symbol, orderBy, order, language, searchText, categoryCode, newsType, pageSize, pageIndex |
marketdata_get_company_news_detail | Lấy chi tiết 1 tin tức công ty theo NewsId | newsId, language | — |
marketdata_list_corporate_actions | Lấy sự kiện doanh nghiệp (chia cổ tức, họp ĐHCĐ, giao dịch nội bộ...) theo mã cổ phiếu | — | eventCode, symbol, fromDate, toDate, pageIndex, pageSize, orderBy, order, dateType, exchange, language |
marketdata_list_corporate_actions_3month | Lấy sự kiện doanh nghiệp 3 tháng gần nhất theo mã cổ phiếu (chia cổ tức, họp ĐHCĐ, giao dịch nội bộ... — fromDate/toDate do server tự tính, không nhận input) | — | eventCode, symbol, pageIndex, pageSize, orderBy, order, dateType, exchange, language |
8. Dòng tiền nhà đầu tư
Giao dịch theo loại nhà đầu tư (tổ chức/cá nhân, trong/ngoài nước) của một mã.
Ví dụ hỏi: "Khối ngoại đang mua hay bán ròng mã X?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_get_investor_type_trade_by_issues | Lấy dữ liệu giao dịch theo loại nhà đầu tư (tổ chức/cá nhân, trong/ngoài nước) của một mã chứng khoán | symbol | investorType, boardId, fromDate, toDate |
9. Ngành / Phân loại doanh nghiệp
Danh sách công ty theo ngành ICB, công ty cùng ngành, chỉ số bình quân ngành, nhận định ngành theo rổ SSI100.
Ví dụ hỏi: "Ngành nào đang có P/E thấp nhất? Những công ty nào cùng ngành với VNM?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_list_icb_industry | Lấy chỉ số tài chính bình quân theo ngành ICB (P/E, P/B, ROE, ROA, biến động giá...) | — | icbCode, icbLevel, exchange, pageIndex, pageSize |
marketdata_list_sectors_data | Lấy danh sách ngành (ICB) kèm công ty thuộc từng ngành | — | level, icbCode, language, pageSize, pageIndex |
marketdata_list_company_in_same_industry | Lấy danh sách công ty cùng ngành với mã cổ phiếu chỉ định | symbol | pageSize, pageIndex, language, similarLevel |
marketdata_get_ssi100_info | Lấy nhận định/đánh giá ngành theo rổ chỉ số SSI100 | — | symbol, industry |
10. Vĩ mô / Lãi suất / Ngoại tệ
Lãi suất ngân hàng, tỷ giá ngoại tệ.
Ví dụ hỏi: "Lãi suất tiết kiệm ngân hàng VCB hiện nay?"
| Tool | Chức năng | Bắt buộc | Tuỳ chọn |
|---|---|---|---|
marketdata_get_bank_interest_rate | Lấy lãi suất ngân hàng theo tên ngân hàng | bankName | source, fromDate, toDate |
marketdata_get_foreign_currency_converter | Lấy tỷ giá ngoại tệ theo ngân hàng/loại tiền | — | currencyCode, source, bank, fromDate, toDate |
Các tool "tự tính khoảng ngày"
Một số tool có phiên bản rút gọn, không cần nhập ngày vì hệ thống tự tính khoảng thời gian gần nhất:
| Tool | Khoảng thời gian tự động |
|---|---|
marketdata_get_index_daily_data_6month | 6 tháng gần nhất |
marketdata_get_stock_statistic_by_range_1month | 1 tháng gần nhất |
marketdata_list_company_news_1month | 1 tháng gần nhất |
marketdata_list_corporate_actions_3month | 3 tháng gần nhất |
marketdata_list_finance_balance_sheet_1year, ..._income_statement_1year, ..._cash_flow_1year | 1 năm gần nhất (khoảng 4 quý báo cáo) |
Nếu bạn cần khoảng thời gian khác, hãy nêu rõ (VD "từ 01/01/2026 đến 30/06/2026"), AI sẽ chuyển sang tool bản đầy đủ có nhận ngày.
Khi Tool không trả về kết quả
| Tình huống | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| AI báo thiếu thông tin | Câu hỏi chưa nêu mã cổ phiếu, khoảng ngày hoặc loại dữ liệu bắt buộc | Bổ sung thông tin AI hỏi lại |
| Yêu cầu bị từ chối do khoảng ngày | Khoảng ngày vượt 730 ngày | Chia nhỏ thành nhiều khoảng, mỗi khoảng tối đa 730 ngày |
| Kết quả rỗng | Mã không tồn tại, hoặc không có dữ liệu trong khoảng đã chọn | Kiểm tra lại mã, mở rộng khoảng ngày |
| Lỗi kết nối tạm thời | Hệ thống dữ liệu phía SSI bận hoặc đang bảo trì | Thử lại sau; nếu kéo dài, liên hệ đội hỗ trợ SSI |
Lưu ý về dữ liệu
Dữ liệu chỉ mang tính tham khảo, không phải khuyến nghị đầu tư. Với giá và chỉ số theo thời gian thực, hãy đối chiếu thêm nguồn công bố chính thức (SSI iBoard, HOSE, HNX, UBCKNN) trước khi ra quyết định.