> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# TokenLab MCP Server

> Kết nối MCP client với tính năng khám phá mô hình, giá, chat tương thích OpenAI và endpoint inference gốc của TokenLab.

[TokenLab MCP server](https://github.com/hedging8563/tokenlab-mcp-server) cung cấp cho các agent tương thích MCP khả năng khám phá mô hình trực tiếp, giá, Chat Completions tương thích OpenAI và các công cụ inference gốc.

Hãy sử dụng khi agent cần so sánh mô hình, kiểm tra định dạng request, xem giá hoặc gọi TokenLab qua OpenAI Chat Completions, Responses, Anthropic Messages hay Gemini generateContent.

<Note>
  Các công cụ danh mục công khai không yêu cầu TokenLab API key. Đặt `TOKENLAB_API_KEY` để sử dụng bốn công cụ inference trả phí.
</Note>

## Những gì server cung cấp

* Khám phá mô hình trực tiếp từ `https://api.tokenlab.sh/v1/models`.
* Tra cứu chi tiết mô hình từ `/v1/models/{model}`.
* Tra cứu giá cả từ `/v1/models/{model}/pricing`.
* Tổng quan API mà agent có thể đọc được từ `https://api.tokenlab.sh/llms.txt`.
* Hướng dẫn về họ endpoint cho chat tương thích với OpenAI, Responses, Anthropic Messages, Gemini, media, audio, embeddings, rerank và dịch thuật.
* Inference tùy chọn qua Chat Completions tương thích OpenAI, Responses, Anthropic Messages và Gemini generateContent.

## Cài đặt từ GitHub

Clone repository công khai và cài đặt các dependency:

```bash theme={null}
git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
```

Khởi động server qua stdio:

```bash theme={null}
npm start
```

Biến môi trường tùy chọn `TOKENLAB_API_BASE` có giá trị mặc định là `https://api.tokenlab.sh`.

## Cài đặt trong Codex

Thêm máy chủ danh mục công khai vào cấu hình Codex:

```bash theme={null}
codex mcp add tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

Bắt đầu một phiên Codex mới sau khi thêm máy chủ. Các công cụ danh mục công khai không cần `TOKENLAB_API_KEY`.

Để bật các công cụ inference, hãy thêm TokenLab API key khi đăng ký server:

```bash theme={null}
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

## Cài đặt trong Cline

Cài đặt server stdio đã phát hành bằng Cline CLI:

```bash theme={null}
cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server
```

Lệnh này đã được xác minh bằng Cline CLI và hoàn tất không có cảnh báo thiết lập. Các công cụ danh mục công khai hoạt động ngay; đặt `TOKENLAB_API_KEY` trong môi trường Cline khi cần công cụ inference.

## Cấu hình Claude Desktop

Thêm package npm đã phát hành vào cấu hình MCP client:

```json theme={null}
{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"]
    }
  }
}
```

Khởi động lại MCP client sau khi lưu cấu hình.

## Cursor, Windsurf và các MCP Client khác

Sử dụng cùng lệnh và args trong bất kỳ client nào hỗ trợ stdio MCP server:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@tokenlabai/mcp-server"],
  "env": {
    "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
  }
}
```

Nếu client của bạn lưu trữ các server có tên, hãy sử dụng `tokenlab-model-catalog` làm tên server.

## Các công cụ (Tools)

| Công cụ                    | Mục đích                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_models`              | Liệt kê các mô hình TokenLab công khai. Có thể lọc tùy chọn với `recommended_for` như `image`, `video`, `embedding`, `rerank` hoặc `translation`. |
| `get_model`                | Lấy chi tiết công khai và định dạng request được hỗ trợ của một mô hình.                                                                          |
| `get_model_pricing`        | Lấy chi tiết giá cả công khai của một mô hình.                                                                                                    |
| `compare_models`           | So sánh chi tiết và giá của nhiều ID mô hình.                                                                                                     |
| `create_chat_completion`   | Gọi endpoint tương thích OpenAI `/v1/chat/completions`, hỗ trợ tin nhắn đa phương thức và tool calling. Yêu cầu `TOKENLAB_API_KEY`.               |
| `create_response`          | Gọi endpoint `/v1/responses`. Yêu cầu `TOKENLAB_API_KEY`.                                                                                         |
| `create_anthropic_message` | Gọi endpoint Anthropic Messages `/v1/messages`. Yêu cầu `TOKENLAB_API_KEY`.                                                                       |
| `create_gemini_content`    | Gọi endpoint Gemini native `generateContent`. Yêu cầu `TOKENLAB_API_KEY`.                                                                         |
| `get_api_overview`         | Lấy tổng quan `llms.txt` của TokenLab để hướng dẫn về endpoint cho agent.                                                                         |

Các công cụ inference trả về kết quả JSON thông thường. Streaming được chủ động tắt cho các lệnh gọi công cụ MCP.

## Quy trình làm việc khuyến nghị cho Agent

1. Gọi `list_models` khi người dùng chưa chỉ định tên mô hình.
2. Sử dụng `recommended_for` cho các tác vụ không phải chat, chẳng hạn như image, video, music, 3D, TTS, STT, embeddings, rerank hoặc translation.
3. Gọi `get_model` trước khi xây dựng một request không phải chat, thử lại một request thất bại hoặc chuyển đổi giữa các họ endpoint.
4. Gọi `get_model_pricing` khi chi phí mô hình ảnh hưởng đến lựa chọn của người dùng.
5. Sử dụng `compare_models` khi lựa chọn phụ thuộc vào nhiều ứng viên.
6. Gọi công cụ inference phù hợp với hợp đồng API cần thiết hoặc dùng `get_api_overview` để xem bản đồ tóm tắt các họ API của TokenLab.

## Hướng dẫn về Endpoint gốc

TokenLab hỗ trợ các route tương thích với OpenAI và các họ endpoint gốc. MCP server giúp agent chọn đúng route trước khi viết code:

| Họ endpoint             | Route phổ biến                                                           |
| ----------------------- | ------------------------------------------------------------------------ |
| Chat tương thích OpenAI | `/v1/chat/completions`                                                   |
| Responses               | `/v1/responses`                                                          |
| Anthropic Messages      | `/v1/messages`                                                           |
| Gemini native           | `/v1beta/models/{model}:generateContent`                                 |
| Images                  | `/v1/images/generations`, `/v1/images/edits`                             |
| Video                   | `/v1/videos/generations`                                                 |
| Music                   | `/v1/music/generations`                                                  |
| 3D                      | `/v1/3d/generations`                                                     |
| Audio                   | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Embeddings và rerank    | `/v1/embeddings`, `/v1/rerank`                                           |
| Dịch văn bản            | `/v1/translations`                                                       |

## Model Explorer được lưu trữ

Các client hỗ trợ Streamable HTTP có thể kết nối tới:

```text theme={null}
https://tokenlab-model-explorer.vercel.app/mcp
```

Explorer được lưu trữ là công khai và cung cấp `open_tokenlab_model_explorer`, `compare_tokenlab_models` cùng `generate_tokenlab_endpoint_example`. Dùng server npm cục bộ ở trên khi cần đủ chín công cụ hoặc inference có thông tin xác thực.

## Sử dụng với TokenLab Skills

MCP server hữu ích tại thời điểm runtime, trong khi [TokenLab skills repository](https://github.com/hedging8563/tokenlab-skills) hướng dẫn các agent lập trình cách tạo và sửa chữa code tích hợp.

Sử dụng cả hai khi có thể:

* MCP server: khám phá các mô hình hiện tại, giá cả và chi tiết endpoint.
* Skill `tokenlab-api-integration`: tạo các ví dụ API có thể chạy được và xử lý các lỗi TokenLab có cấu trúc.
* Skill `tokenlab-model-picker`: chọn các mô hình mạnh mẽ cho tác vụ của người dùng.
* Skill `tokenlab-native-endpoints`: quyết định khi nào nên sử dụng các route Responses, Anthropic Messages, Gemini, media, audio, embedding, rerank hoặc translation.

## Khắc phục sự cố

<AccordionGroup>
  <Accordion title="Client không thể khởi động server">
    Xác nhận Node.js từ phiên bản 18.17 trở lên, sau đó chạy `npx -y @tokenlabai/mcp-server` một lần trong terminal để xem lỗi npm hoặc mạng.
  </Accordion>

  <Accordion title="Danh sách mô hình trống">
    Xác minh rằng máy có thể truy cập `https://api.tokenlab.sh/v1/models`. Nếu bạn ghi đè `TOKENLAB_API_BASE`, hãy đảm bảo nó không bao gồm dấu gạch chéo ở cuối.
  </Accordion>

  <Accordion title="Agent vẫn chọn các ID mô hình cũ">
    Yêu cầu agent gọi `list_models` hoặc `get_model` trước khi hardcode tên mô hình. Việc kết hợp MCP server với `tokenlab-model-picker` sẽ mang lại kết quả tốt hơn.
  </Accordion>

  <Accordion title="Server này có thể gọi các API inference trả phí của TokenLab không?">
    Có. Đặt `TOKENLAB_API_KEY`, sau đó dùng `create_chat_completion`, `create_response`, `create_anthropic_message` hoặc `create_gemini_content`. Các công cụ danh mục và giá vẫn dùng được mà không cần key.
  </Accordion>
</AccordionGroup>

## Tài nguyên

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/hedging8563/tokenlab-mcp-server">
    Mã nguồn và hướng dẫn thiết lập cục bộ
  </Card>

  <Card title="TokenLab Skills" icon="sparkles" href="https://github.com/hedging8563/tokenlab-skills">
    Các kỹ năng agent được duy trì cho các tích hợp TokenLab
  </Card>

  <Card title="Model Catalog API" icon="list" href="https://api.tokenlab.sh/v1/models">
    Endpoint khám phá mô hình công khai
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    Tổng quan API TokenLab mà agent có thể đọc được
  </Card>

  <Card title="Máy chủ MCP trên Glama" icon="globe" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-mcp-server">
    Xem trang TokenLab MCP Server đã được xác minh
  </Card>

  <Card title="Trình khám phá mô hình Glama" icon="search" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-openai-apps-model-explorer">
    Khám phá mô hình, giá và ví dụ về endpoint gốc
  </Card>

  <Card title="Mục MCP.so" icon="compass" href="https://mcp.so/servers/tokenlab-mcp-server">
    Khám phá TokenLab trong danh mục AI & Agents
  </Card>

  <Card title="Model Explorer được lưu trữ" icon="rocket" href="https://tokenlab-model-explorer.vercel.app">
    Mở model explorer công khai và endpoint MCP từ xa
  </Card>
</CardGroup>