MCP Streamable HTTP · 2025-03-26cungdautu-news-mcp v1.0.0

Tài liệu tích hợp MCP — Cùng Đầu Tư

Hướng dẫn kết nối trực tiếp các công cụ AI (Claude, Cursor, VS Code Copilot, OpenAI Codex, Google Antigravity) với hệ thống quản trị Tin tức & Bản tin Nhịp đập của Cùng Đầu Tư.

← Quay lại trang Kết nối MCP

Mục lục:Tổng quan & Xác thực Claude Cursor VS Code Copilot OpenAI Codex Google Antigravity Danh sách 7 Tools Prompt mẫu & Quy chuẩn Kiểm tra & Xử lý lỗi

1. Tổng quan & Cơ chế xác thực theo tài khoản

Máy chủ MCP của Cùng Đầu Tư hoạt động theo giao thức Model Context Protocol (Streamable HTTP). Mỗi tài khoản Admin khi đăng nhập vào trang quản trị được cấp một khoá kết nối riêng có định dạng cdt_mcp_<uid8>_<nonce>_<signature>.

Cách 1: Kết nối qua URL 1 dòng (Khuyên dùng)

Truyền trực tiếp tham số ?api_key=... trong URL. Tương thích ngay với Claude Connectors, Cursor, VS Code và OpenAI Codex:

https://landing.cungdautu.vn/mcp?api_key=cdt_mcp_<your_account_key>

Cách 2: Kết nối qua HTTP Header

Sử dụng endpoint gốc kết hợp với header X-API-Key hoặc Authorization: Bearer:

Endpoint: https://landing.cungdautu.vn/mcp

Header: X-API-Key: cdt_mcp_<your_account_key>

Lưu ý bảo mật: Khi bạn bấm Regenerate key ở trang Kết nối MCP, mã nonce của tài khoản sẽ thay đổi và khoá cũ sẽ bị vô hiệu hoá ngay lập tức mà không ảnh hưởng tới các tài khoản Admin khác.

2. Hướng dẫn cài đặt chi tiết cho từng công cụ AI

Claude (Claude Desktop / Web & Claude Code CLI)

#claude

A. Kết nối trên giao diện Claude (Settings → Connectors):

Mở ứng dụng Claude → vào Settings → Connectors → chọn Add custom connector.
Dán đường dẫn MCP cá nhân của bạn vào ô URL rồi xác nhận kết nối:

https://landing.cungdautu.vn/mcp?api_key=cdt_mcp_<your_account_key>

B. Kết nối bằng một lệnh trên Claude Code CLI:

claude mcp add --transport http cungdautu-mcp "https://landing.cungdautu.vn/mcp?api_key=cdt_mcp_<your_account_key>" --header "X-API-Key: cdt_mcp_<your_account_key>"

Cursor IDE

#cursor

Mở Cursor Settings (Cmd/Ctrl + ,) → chọn Tools & MCP → nhấn Add MCP server (hoặc mở trực tiếp file .cursor/mcp.json).
Thêm cấu hình máy chủ cungdautu-mcp như bên dưới và lưu file:

{
  "mcpServers": {
    "cungdautu-mcp": {
      "url": "https://landing.cungdautu.vn/mcp?api_key=cdt_mcp_<your_account_key>"
    }
  }
}

GitHub Copilot (VS Code)

#vscode

Mở Command Palette (Cmd/Ctrl + Shift + P) → chạy lệnh MCP: Add Server → chọn loại HTTP và dán URL của bạn.
Hoặc tạo/chỉnh sửa file .vscode/mcp.json trong thư mục dự án với nội dung:

{
  "servers": {
    "cungdautu-mcp": {
      "type": "http",
      "url": "https://landing.cungdautu.vn/mcp?api_key=cdt_mcp_<your_account_key>"
    }
  }
}

OpenAI Codex

#codex

Mở file cấu hình ~/.codex/config.toml (hoặc .codex/config.toml trong thư mục dự án).
Thêm khối cấu hình dưới đây rồi khởi động lại phiên Codex:

[mcp_servers.cungdautu]
url = "https://landing.cungdautu.vn/mcp?api_key=cdt_mcp_<your_account_key>"

Google Antigravity

#antigravity

Trong khung Agent của Antigravity, bấm biểu tượng "..." → chọn Manage MCP Servers → View raw config (file ~/.gemini/antigravity/mcp_config.json).
Thêm mục cungdautu-mcp vào mcpServers:

{
  "mcpServers": {
    "cungdautu-mcp": {
      "serverUrl": "https://landing.cungdautu.vn/mcp",
      "headers": {
        "X-API-Key": "cdt_mcp_<your_account_key>"
      }
    }
  }
}

3. Danh mục 7 công cụ (Tools) trên Cùng Đầu Tư MCP Server

Sau khi kết nối thành công, trợ lý AI của bạn có thể gọi trực tiếp 7 công cụ dưới đây để tra cứu và biên tập dữ liệu trên landing.cungdautu.vn:

list_recent_newsRead

Tra cứu danh sách bài viết tin tức gần đây trong bảng MarketNews. Luôn gọi công cụ này trước khi đăng bài mới để kiểm tra trùng lặp (theo externalId, title hoặc sourceUrl) hoặc tìm id/externalId của bài cần biên tập.

Tham số	Kiểu	Mô tả
limit	integer	Số lượng bài tối đa cần lấy (mặc định 20, tối đa 100).
symbol	string	Lọc theo mã cổ phiếu hoặc chỉ số (ví dụ: 'FPT', 'VCB', 'HPG', 'VNINDEX').
category	string	Lọc theo chuyên mục (ví dụ: 'Thị trường', 'Doanh nghiệp', 'Vĩ mô', 'Quốc tế').
status	integer	Trạng thái hiển thị: 1 = đang hiển thị (mặc định), 0 = đang ẩn, -1 = lấy tất cả.
featuredOnly	boolean	Chỉ lấy các bài tin tiêu điểm / nổi bật (isFeatured = true).
search	string	Từ khoá tìm kiếm theo tiêu đề (Title) hoặc mã ngoài (ExternalId).

Ví dụ JSON Arguments:

{
  "limit": 10,
  "symbol": "FPT",
  "status": 1
}

get_news_detailRead

Xem toàn bộ nội dung chi tiết (HTML content, summary, nguồn, trạng thái...) của một bài viết theo id (UUID) hoặc externalId.

Tham số	Kiểu	Mô tả
id	string	UUID của bài viết cần xem chi tiết.
externalId	string	Mã định danh ngoài (ExternalId) của bài viết.

Ví dụ JSON Arguments:

{
  "externalId": "cdt-20261102-fpt-kqkd-q3"
}

upsert_newsWrite

Đăng mới hoặc cập nhật (upsert idempotent theo externalId hoặc id) 1 bài viết hoặc danh sách nhiều bài viết (tối đa 50 bài/lần) vào bảng MarketNews. Khi cập nhật bài đã có, các trường để trống sẽ giữ nguyên giá trị cũ.

Tham số	Kiểu	Mô tả
externalId*	string	Mã định danh duy nhất cho bài viết (ví dụ: 'cdt-20261102-vcb-lnq3'). Giúp cập nhật an toàn mà không tạo bài trùng.
title*	string	Tiêu đề bài viết (tối đa 500 ký tự).
summary	string	Đoạn tóm tắt ngắn (sapo, tối đa 4.000 ký tự) hiển thị trên thẻ tin tức.
content	string	Nội dung chi tiết bài viết (hỗ trợ HTML như <p>, <h3>, <ul>, <li>, <strong>, tối đa 200.000 ký tự).
symbol	string	Mã cổ phiếu hoặc chỉ số liên quan (ví dụ: 'FPT', 'VCB', 'VNINDEX').
category	string	Chuyên mục ('Thị trường', 'Doanh nghiệp', 'Vĩ mô', 'Quốc tế', 'Góc nhìn tham khảo').
author	string	Tác giả / đơn vị biên tập (nên dùng: 'Ban Biên Tập Cùng Đầu Tư' hoặc 'Cùng Đầu Tư · AI Insight').
thumbnailUrl	string	URL ảnh đại diện tuyệt đối (https://...).
isFeatured	boolean	true = đặt làm tin tiêu điểm nổi bật, false = tin thường.
status	integer	0 = lưu bản nháp chờ Admin duyệt (mặc định khi tạo mới qua MCP), 1 = hiển thị công khai.
articles	array	Mảng nhiều bài viết (tối đa 50 bài) nếu muốn đẩy hàng loạt trong 1 lần gọi.

Ví dụ JSON Arguments:

{
  "externalId": "cdt-20261102-fpt-tang-truong-ai",
  "title": "FPT đẩy mạnh mảng dịch vụ CNTT nước ngoài trong quý mới",
  "summary": "Doanh thu khối công nghệ thông tin thị trường quốc tế tiếp tục duy trì đà tăng trưởng hai chữ số nhờ nhu cầu chuyển đổi số và AI.",
  "content": "<p>Theo số liệu cập nhật mới nhất, mảng dịch vụ CNTT tại Nhật Bản và APAC tiếp tục dẫn dắt tốc độ tăng trưởng doanh thu...</p>",
  "symbol": "FPT",
  "category": "AI Insight",
  "author": "Ban Biên Tập Cùng Đầu Tư",
  "sourceName": "Cùng Đầu Tư · AI Insight",
  "isFeatured": true,
  "status": 0
}

update_news_statusWrite

Cập nhật nhanh trạng thái hiển thị (status: 1 = hiện, 0 = ẩn) hoặc bật/tắt tin tiêu điểm (isFeatured: true/false) cho 1 hoặc nhiều bài viết cùng lúc.

Tham số	Kiểu	Mô tả
id / externalId	string	Định danh bài viết cần đổi trạng thái.
status	integer	1 = hiển thị công khai, 0 = ẩn bài viết.
isFeatured	boolean	true = đánh dấu tin nổi bật, false = bỏ nổi bật.
items	array	Danh sách nhiều phần tử { id/externalId, status, isFeatured } để cập nhật hàng loạt.

Ví dụ JSON Arguments:

{
  "externalId": "cdt-20261102-fpt-tang-truong-ai",
  "status": 1,
  "isFeatured": true
}

list_recent_briefingsRead

Tra cứu danh sách các bản tin tóm tắt điểm nhấn thị trường ('Nhịp đập thị trường' trên trang chủ, bảng site_briefings) gần đây.

Tham số	Kiểu	Mô tả
limit	integer	Số lượng bản tin cần lấy (mặc định 10, tối đa 50).

Ví dụ JSON Arguments:

{
  "limit": 5
}

upsert_briefingWrite

Đăng mới hoặc cập nhật bản tin tóm tắt điểm nhấn thị trường ('Nhịp đập thị trường' hiển thị nổi bật trên trang chủ).

Tham số	Kiểu	Mô tả
id	string	UUID của bản tin nếu muốn cập nhật bản tin đã có; bỏ trống nếu tạo mới.
title*	string	Tiêu đề bản tin Nhịp đập thị trường.
bullets*	string[]	Danh sách các ý chính (ý đầu tiên là tổng quan phiên giao dịch, các ý tiếp theo là từng điểm nhấn ngành / cổ phiếu).
source	string	Nguồn hiển thị (mặc định: 'Cùng Đầu Tư · AI Insight').
status	string	'draft' (mặc định khi tạo mới để chờ Admin duyệt) hoặc 'published'.

Ví dụ JSON Arguments:

{
  "title": "Nhịp đập thị trường: Dòng tiền lan tỏa nhóm Ngân hàng & Công nghệ",
  "bullets": [
    "VN-Index duy trì sắc xanh tích cực với thanh khoản cải thiện so với trung bình 5 phiên gần nhất.",
    "Nhóm cổ phiếu VCB, BID, FPT đóng vai trò trụ đỡ chính cho chỉ số chung.",
    "Khối ngoại thu hẹp đà bán ròng và quay lại mua ròng nhóm cổ phiếu đầu ngành công nghệ."
  ],
  "source": "Cùng Đầu Tư · AI Insight",
  "status": "draft"
}

send_notification_emailNotify

Gửi email báo cáo tổng hợp tin tức tùy chỉnh về hộp thư biên tập (mặc định cungdautu@gmail.com).

Tham số	Kiểu	Mô tả
subject*	string	Tiêu đề email báo cáo.
body*	string	Nội dung email (hỗ trợ HTML).
to	string	Địa chỉ người nhận (mặc định: 'cungdautu@gmail.com').

Ví dụ JSON Arguments:

{
  "subject": "[Cùng Đầu Tư] Báo cáo tổng hợp tin tức đầu ngày",
  "body": "<p>Đã cập nhật 5 tin doanh nghiệp và 1 bản tin Nhịp đập thị trường.</p>"
}

4. Quy định về ngôn ngữ, nội dung pháp lý & Prompt mẫu

Quy tắc tuân thủ pháp lý & thuật ngữ bắt buộc (Bản 1.0 · 02/11/2026):

Bản chất pháp lý: Cùng Đầu Tư cung cấp công cụ đọc dữ liệu thị trường và thống kê, không phải công ty chứng khoán và không thực hiện nghiệp vụ tư vấn đầu tư chứng khoán. Tuyệt đối không phát hành danh sách mã kèm ý kiến mua, bán hoặc nắm giữ dưới tên nền tảng. Một câu ghi “chỉ mang tính tham khảo” không khắc phục được nội dung mang tính chỉ dẫn giao dịch.
Nhãn minh bạch AI & Nguồn tin: Luôn gọi list_recent_news trước khi gọi upsert_news. Đặt author = Cùng Đầu Tư · AI Insight, sourceName = AI tổng hợp từ [Tên nguồn gốc] kèm sourceUrl và thời điểm công bố. Tách dữ kiện đã công bố khỏi kịch bản có điều kiện.
Từ ngữ cần chặn tuyệt đối: “Nên mua”, “bán ngay”, “giữ tiếp”, “canh mua”, “điểm vào”, “vùng mua an toàn”, “chốt lời”, “cắt lỗ ở X”, “kèo VIP”, “hàng ngon”, “top đáng mua”, “cá mập vào hàng”, “đội lái đánh lên”, “lãi chắc”, “dư địa lãi X%”, “gia tăng tỷ trọng”, “cố vấn AI”, “Cùng Đầu Tư Research”, “CFA Research / CFA View”.
Cách viết chuẩn tuân thủ: Chỉ nêu sự kiện và phép tính kiểm chứng được (ví dụ: “Đóng cửa vượt EMA21”, “Vùng giá đã chạm”, “Giao dịch khớp vượt bình quân 20 phiên”, “Tỷ trọng GTGD ngành đã tăng”, “Giá mục tiêu theo báo cáo [tổ chức], ngày [...]”).

Tổng hợp & lưu nháp bản tin Nhịp đập thị trường chờ duyệt

Hãy sử dụng MCP server "cungdautu-mcp":
1. Gọi list_recent_briefings (limit: 3) và list_recent_news (limit: 10) để nắm bối cảnh các bản tin vừa đăng.
2. Soạn và gọi upsert_briefing để đẩy 1 bản tin Nhịp đập thị trường mới với tiêu đề ngắn gọn, 3-4 gạch đầu dòng súc tích về diễn biến dòng tiền và nhóm ngành tâm điểm. Đặt source = "Cùng Đầu Tư · AI Insight" và status = "draft" để lưu bản nháp chờ Admin duyệt đăng.

Kiểm tra trùng lặp & lưu nháp bài phân tích AI Insight chờ duyệt

Hãy sử dụng MCP server "cungdautu-mcp":
1. Gọi list_recent_news với symbol = "FPT" (status = -1) để kiểm tra xem chủ đề này đã có bài viết chưa.
2. Nếu chưa trùng, hãy biên tập bài phân tích mới và gọi upsert_news với:
   - externalId theo định dạng "cdt-YYYYMMDD-<slug>"
   - author = "Ban Biên Tập Cùng Đầu Tư"
   - sourceName = "Cùng Đầu Tư · AI Insight"
   - category = "AI Insight"
   - status = 0 (lưu bản nháp để Admin kiểm duyệt và bấm Duyệt đăng trên trang quản trị)

5. Kiểm tra kết nối nhanh & Xử lý sự cố

Bạn có thể kiểm tra trực tiếp khoá MCP của mình từ Terminal bằng lệnh curl dưới đây:

curl -sS -X POST "https://landing.cungdautu.vn/mcp?api_key=cdt_mcp_<your_account_key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• Lỗi HTTP 401 Unauthorized: Kiểm tra lại xem bạn hoặc quản trị viên có vừa nhấn Regenerate key hay không. Nếu có, hãy copy lại URL hoặc chạy lại Prompt cài đặt tự động.

• AI không nhìn thấy danh sách Tools: Sau khi sửa file cấu hình (mcp.json / config.toml), hãy nhấn Reload / Restart MCP Server trong phần cài đặt của trình soạn thảo để nạp lại danh sách công cụ.