MCP server — dùng VieNeu trong Claude, ChatGPT và các app khác

VieNeu có sẵn một MCP server (Model Context Protocol) chạy trên máy chủ của VieNeu. Bạn thêm một địa chỉ vào trợ lý AI, đăng nhập tài khoản VieNeu, rồi nhờ đọc văn bản tiếng Việt bằng lời thường — trợ lý tự tìm giọng, tạo audio, rồi phát ngay hoặc đưa bạn link tải.

https://api.vieneu.io/mcp

Không cần cài gì. Lần đầu dùng, trợ lý mở trang đăng nhập VieNeu trong trình duyệt (OAuth 2.1); công cụ nào không đăng nhập được thì có thể dùng API key.

Trước khi bắt đầu: tài khoản VieNeu cần có gói token còn hạn. Chưa có gói thì không kết nối được, vì lần tạo audio nào cũng sẽ thất bại.

Chọn app bạn dùng

App	Cách kết nối	Trình phát trong khung chat	Hướng dẫn
Claude (web, máy tính, điện thoại)	Thêm connector tuỳ chỉnh, đăng nhập	Có	Claude
ChatGPT	Bật Developer mode → thêm app, đăng nhập	Có	ChatGPT
Claude Code	Một lệnh, rồi /mcp	—	Claude Code
Cursor	Một chạm hoặc mcp.json; đăng nhập hoặc API key	Có	Cursor
VS Code (GitHub Copilot)	Một chạm hoặc mcp.json; đăng nhập hoặc API key	Có (thử nghiệm)	VS Code
OpenAI API / Agents SDK	Công cụ mcp trong code	—	OpenAI API
Windsurf (Devin Desktop), Gemini CLI, Codex CLI, Zed, Goose, LM Studio	File cấu hình	Chỉ Goose	Các app khác

Gặp trục trặc? Xem Xử lý sự cố.

Nói gì với trợ lý

"VieNeu làm được gì?"

Trợ lý gọi list_capabilities và liệt kê những việc làm được ở đây, mỗi việc một câu ví dụ, kèm việc nào trừ token. Ở app có trình phát trong khung chat, danh sách hiện thành một thẻ: bấm vào câu ví dụ là câu đó được gửi vào khung chat.

"Tìm giọng nữ miền Bắc đọc tin tức."

Trợ lý gọi list_voices. Miễn phí.

"Đọc đoạn này bằng giọng Thu Trang."

Trợ lý gọi text_to_speech. Ở app có trình phát, một trình phát nhỏ hiện ngay trong khung chat — bấm là nghe. Luôn có kèm link tải (hạn 24 giờ; MP3 với văn bản tới 1.500 ký tự). Audio cũng được lưu trong Thư viện trên vieneu.io. Việc này trừ token trong gói của bạn, y như gọi cùng yêu cầu qua API.

"Chèn tiếng cười sau câu đầu."

Trợ lý gọi list_emotion_tags rồi viết thẻ như [cười] vào văn bản trước khi đọc.

"Làm sách nói từ truyện này — giọng nữ miền Bắc dẫn chuyện, mỗi nhân vật một giọng."

Trợ lý chuyển văn bản thành kịch bản, chọn giọng, báo chi phí; bạn đồng ý thì VieNeu tạo mỗi chương một file MP3 ở chế độ nền. Xem Sách nói.

Các công cụ

Công cụ	Làm gì	Chi phí
list_capabilities	Những việc kết nối này làm được, mỗi việc một câu ví dụ	Miễn phí
list_voices	Tìm giọng tài khoản dùng được, gồm cả giọng bạn tự nhân bản	Miễn phí
text_to_speech	Đọc văn bản tiếng Việt; trả link tải và thời lượng	Trừ token
get_speech_status	Xem một job dài còn đang xử lý; trả link khi xong	Miễn phí
list_emotion_tags	Phong cách đọc, và thẻ như [cười] để chèn vào văn bản	Miễn phí
get_token_balance	Số token dùng được ngay, hạn mức của gói và giờ làm mới, và ước tính còn đọc được bao nhiêu ký tự	Miễn phí

Sáu công cụ nữa — create_audiobook, add_audiobook_chapter, start_audiobook, get_audiobook, list_audiobooks, cancel_audiobook — dùng để làm sách nói; xem ở trang Sách nói.

list_voices

Tham số	Kiểu	Ghi chú
search	chuỗi, tuỳ chọn	Vài từ mô tả giọng (nữ miền Bắc trầm ấm, male south) hoặc tên giọng (Thu Trang). Cách đọc các từ xem bên dưới.
limit	1–100, tuỳ chọn	Mặc định 25. Câu trả lời cho biết còn bao nhiêu giọng khớp nữa.

Mỗi dòng có dạng id (giới tính, vùng) "Tên" - mô tả. text_to_speech cần đúng id như hiển thị — id trông giống tên người (Thu Trang) và không đoán được.

Cách search đọc các từ:

• Giới tính và vùng miền lấy từ thông tin của giọng, không lấy từ mô tả: nữ, nam, miền Bắc, miền Nam, miền Trung, hoặc female, male, north, south, central. nam đứng riêng nghĩa là giọng nam; muốn nói vùng miền thì viết miền Nam.
• Các từ khác khớp nguyên từ trong id, tên hoặc mô tả, không phân biệt hoa thường. Từ viết có dấu phải khớp đúng dấu (già không ra giọng tên Gia); viết không dấu thì khớp cả hai, và từ 4 chữ cái trở lên khớp cả phần đầu của từ.
• Từ không mô tả giọng nào, như giọng hay đọc, được bỏ qua.
• Tên giọng (Thùy An, giọng Thu Trang) đưa giọng đó lên đầu.
• Không giọng nào có đủ mọi từ: kết quả là các giọng gần nhất, ưu tiên giọng đúng giới tính và vùng miền, mỗi dòng kết thúc bằng những từ giọng đó còn thiếu: [thiếu: trầm, ấm].

text_to_speech

Tham số	Kiểu	Ghi chú
text	chuỗi	Văn bản tiếng Việt, tối đa 50.000 ký tự. Số, ngày tháng và từ viết tắt tiếng Anh đều được xử lý.
voice	chuỗi, tuỳ chọn	Id giọng lấy từ list_voices. Bỏ trống: giọng mặc định.
speed	0,5–2,0, tuỳ chọn	1,0 là tốc độ tự nhiên.
style	chuỗi, tuỳ chọn	Phong cách đọc lấy từ list_emotion_tags.

Tới 1.500 ký tự, công cụ gọi một lần POST /v1/audio/speech để lấy MP3 và trả link sau giây lát. Văn bản dài hơn thành một job POST /v1/tts (WAV), công cụ chờ khoảng 50 giây; văn bản rất dài có thể vẫn đang xử lý — khi đó câu trả lời kèm mã job và dặn trợ lý gọi get_speech_status sau, không tạo lại (tạo lại sẽ trừ token lần nữa). Dù đường nào, câu trả lời cũng có link, định dạng, thời lượng và giọng — và khi audio đã xong, số token bạn còn lại.

get_speech_status

Tham số	Kiểu	Ghi chú
job_id	chuỗi	Mã job mà text_to_speech trả về.

get_token_balance

Không có tham số. Hỏi "còn bao nhiêu token?", trợ lý sẽ trả lời:

• Dùng được ngay — số token tối đa một lần tạo audio có thể tiêu lúc này: token còn lại của gói, hoặc ít hơn nếu hạn mức ngày/tuần thấp hơn.
• Gói còn bao nhiêu / tổng bao nhiêu, từng hạn mức và giờ làm mới (giờ Việt Nam), ngày gói hết hạn.
• Tổng token của mọi gói còn hạn, nếu bạn có nhiều gói — gói sau dùng tiếp khi gói này hết.
• Ước tính còn đọc được khoảng bao nhiêu ký tự với engine mặc định.

Khi hết token, câu trả lời kèm link bảng giá. Script có thể lấy đúng những số này qua GET /v1/balance.

Trình phát ngay trong khung chat

Ở các app hỗ trợ MCP Apps — Claude (web, máy tính, điện thoại), ChatGPT, Cursor, VS Code (thử nghiệm) và Goose — kết quả của text_to_speech và get_speech_status hiện thành một trình phát ngay trong cuộc trò chuyện: phát/dừng, tua, thời lượng và nút tải. Khi job dài còn chạy, trình phát hiện một đèn xanh nhỏ và tự hỏi get_speech_status (miễn phí), xong là chuyển sang phát được.

Sách nói có trình phát riêng dưới kết quả start_audiobook và get_audiobook: danh sách chương kèm tiến độ, phát nối tiếp nhau, tự cập nhật trong lúc sách đang được tạo.

Claude hỏi một lần trước khi hiện trình phát — chọn Allow (hoặc Always allow). App không hỗ trợ MCP Apps thì hiện câu trả lời kèm link, ngoài ra không có gì khác.

Prompt có sẵn

Server còn có năm prompt — các yêu cầu soạn sẵn, kèm ô để điền chi tiết. App nào hiển thị prompt MCP sẽ liệt kê chúng trong menu: Claude Code là /mcp__vieneu__make_audiobook, VS Code là /mcp.vieneu.make_audiobook (phần giữa là tên bạn đặt cho server). ChatGPT không hiển thị prompt; ở đó cứ hỏi "VieNeu làm được gì?".

Prompt	Nhờ làm gì	Chi tiết cần điền
what_can_vieneu_do	Liệt kê những việc VieNeu làm được	—
read_text	Đọc một đoạn văn	text, voice (tuỳ chọn, vd. "nữ miền Bắc")
make_audiobook	Làm sách nói từ văn bản của bạn, báo giá trước khi tạo	text (tuỳ chọn — dán sau cũng được), narrator (tuỳ chọn)
find_voice	Tìm giọng theo mô tả	description
check_balance	Số token còn lại và hạn mức của gói	—

Dùng API key thay cho đăng nhập

Script, OpenAI API và các app không đăng nhập được có thể gửi một API key trong mỗi request, qua một trong hai header:

X-API-Key: vn_sk_...
Authorization: Bearer vn_sk_...

Tạo key ở trang Nhà phát triển trên vieneu.io. File cấu hình chứa key cũng như chứa mật khẩu — app nào đăng nhập được thì nên đăng nhập, và đừng bao giờ đưa key lên repository. Mỗi trang hướng dẫn app đều chỉ chỗ đặt header.

Tính phí

Mỗi lần gọi công cụ tốn đúng như lời gọi API tương ứng: mỗi lần text_to_speech là một lần tạo audio, tính theo ký tự (tối thiểu 50) nhân hệ số của engine, trừ vào token trong gói. Tạo audio thất bại thì token tự được hoàn. Sách nói tính đúng như vậy, từng chương khi chương đó được tạo, sau khi bạn đồng ý start_audiobook. Mọi công cụ khác đều miễn phí.

Lượt dùng qua MCP hiện ở Nhà phát triển → Sử dụng như mọi lượt gọi API, ghi theo tên kết nối (ví dụ "Claude (MCP)").

Xem và gỡ kết nối

Trên vieneu.io, Nhà phát triển → Dùng VieNeu trong Claude, ChatGPT có địa chỉ để sao chép và danh sách mọi app bạn đã kết nối, kèm ngày kết nối và lần dùng gần nhất. Gỡ kết nối đăng xuất app đó ngay lập tức; muốn dùng lại, app phải xin quyền lại từ đầu.

Lỗi thường gặp

Công cụ dịch lỗi của API thành câu mà trợ lý hiểu và làm theo được.

Bạn thấy	Nguyên nhân	Cách xử lý
Bị yêu cầu đăng nhập lại	Kết nối đã bị gỡ trên vieneu.io, hoặc phiên đăng nhập hết hạn	Kết nối lại từ app
"Tài khoản không đủ quyền hoặc hết token…"	Gói hết token, hết hạn, hoặc không có engine này (HTTP 403)	Nạp thêm hoặc gia hạn trên vieneu.io — thử lại không giúp gì
"Đang gọi quá nhanh…"	Bị giới hạn tần suất (HTTP 429)	Chờ đúng số giây được báo
"Máy chủ tạo giọng đang bận"	Chưa có máy tạo giọng rảnh (HTTP 503)	Thử lại sau vài giây
"Voice … is not available"	Id giọng không có trong danh mục	Chọn id từ list_voices

Xem thêm Xử lý sự cố.

Những gì cố ý không đưa vào

Nhân bản giọng, lồng tiếng và lồng tiếng theo SRT không có ở đây. Các việc này cần tải file lên và tốn nhiều token hơn hẳn mỗi lần; để trợ lý lỡ tay gọi thì trải nghiệm đầu tiên sẽ rất tệ. Dùng web app hoặc Cloud API cho các việc đó.

Dành cho người làm client

• Transport: Streamable HTTP, không giữ phiên. Phiên bản giao thức 2026-07-28, vẫn phục vụ client đời 2025.
• Xác thực: OAuth 2.1 theo đặc tả authorization của MCP. Request chưa xác thực nhận 401 kèm WWW-Authenticate: Bearer resource_metadata="https://api.vieneu.io/.well-known/oauth-protected-resource".
• Metadata: /.well-known/oauth-protected-resource (RFC 9728) và /.well-known/oauth-authorization-server (RFC 8414).
• Client: Client ID Metadata Document và Dynamic Client Registration (/oauth/register). Luôn bắt buộc PKCE S256. Metadata document phải cho phép none (là phương thức ưu tiên hoặc nằm trong token_endpoint_auth_methods_supported). Đăng ký động nhận none, client_secret_post và client_secret_basic, luôn trả về client_secret; secret chỉ bắt buộc với hai phương thức có secret. Redirect loopback (http://127.0.0.1 / localhost) khớp với mọi cổng.
• Scope: tts (thêm offline_access để có refresh token). Access token sống một giờ; refresh token đổi mới sau mỗi lần dùng.
• MCP Apps: ui://vieneu/player.html, ui://vieneu/audiobook.html và ui://vieneu/capabilities.html (text/html;profile=mcp-app); chỉ được tải media từ nguồn lưu trữ của VieNeu. Thẻ chức năng gửi câu ví dụ vào khung chat bằng ui/message khi host hỗ trợ.
• Prompt: what_can_vieneu_do, read_text, make_audiobook, find_voice, check_balance.