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

Source: https://docs.vieneu.io/vi/docs/integrations/mcp/

VieNeu có sẵn một [MCP](https://modelcontextprotocol.io) 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](#using-an-api-key-instead-of-signing-in).

**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](./claude-ai.md) |
| **ChatGPT** | Bật Developer mode → thêm app, đăng nhập | Có | [ChatGPT](./chatgpt.md) |
| **Claude Code** | Một lệnh, rồi `/mcp` | — | [Claude Code](./claude-code.md) |
| **Cursor** | <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=vieneu&config=eyJ1cmwiOiJodHRwczovL2FwaS52aWVuZXUuaW8vbWNwIn0=" target="_self">Một chạm</a> hoặc `mcp.json`; đăng nhập hoặc API key | Có | [Cursor](./cursor.md) |
| **VS Code** (GitHub Copilot) | <a href="vscode:mcp/install?%7B%22name%22%3A%22vieneu%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.vieneu.io%2Fmcp%22%7D" target="_self">Một chạm</a> hoặc `mcp.json`; đăng nhập hoặc API key | Có (thử nghiệm) | [VS Code](./vscode.md) |
| **OpenAI API / Agents SDK** | Công cụ `mcp` trong code | — | [OpenAI API](./openai-api.md) |
| Windsurf (Devin Desktop), Gemini CLI, Codex CLI, Zed, Goose, LM Studio | File cấu hình | Chỉ Goose | [Các app khác](./other-clients.md) |

Gặp trục trặc? Xem [Xử lý sự cố](./troubleshooting.md).

## 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](#the-inline-player), 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](./audiobooks.md).

## 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](./audiobooks.md#tools).

### `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`](../../cloud-api/openai-compatible.md) để 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`](../../cloud-api/overview.md) (**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`](../../cloud-api/overview.md#billing).

## Trình phát ngay trong khung chat {#the-inline-player}

Ở các app hỗ trợ [MCP Apps](https://modelcontextprotocol.io/docs/extensions/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 {#prompts}

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 {#using-an-api-key-instead-of-signing-in}

Script, OpenAI API và các app không đăng nhập được có thể gửi một
[API key](../../cloud-api/overview.md#authentication) 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ố](./troubleshooting.md).

## 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](../../cloud-api/overview.md)
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`](https://api.vieneu.io/.well-known/oauth-protected-resource)
  (RFC 9728) và
  [`/.well-known/oauth-authorization-server`](https://api.vieneu.io/.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`.