TokenLab for Agents: Các mô hình có thể đọc được bằng máy, Định giá, SDK và MCP

Một coding agent tự chọn ID mô hình từ bộ nhớ cuối cùng sẽ chọn phải một ID không còn tồn tại, và nó chỉ phát hiện ra điều đó sau khi nhận lỗi 404 hoặc một hóa đơn bất ngờ. TokenLab MCP cung cấp cho agent một danh mục trực tiếp để kiểm tra trước, nhờ đó nó có thể xác minh ID, định dạng yêu cầu được chấp nhận và giá cả trước khi viết bất kỳ mã tích hợp nào. Ban đầu chúng tôi mô tả server này chỉ ở chế độ chỉ đọc (read-only). Tài liệu được ghi nhận vào ngày 03/10/2026 cho thấy điều ngược lại, vì vậy phiên bản này đã sửa lại thông tin đó và bổ sung một quy trình làm việc cụ thể.

Những điểm chính cần lưu ý

• Server TokenLab MCP có ba cấu hình: catalog (không cần API key), core và full. Chỉ có catalog là không yêu cầu key.
• Với một API key, nó cũng có thể gửi các yêu cầu mô hình, tạo nội dung đa phương tiện, xử lý tệp và kiểm tra các tác vụ bất đồng bộ (async tasks). Nó không phải là chỉ đọc.
• Hãy định tuyến dựa trên tokenlab.accepted_request_formats, tokenlab.pricing, tokenlab.lifecycle và tokenlab.deliveryAvailability. Đừng hard-code thứ tự gợi ý.
• Gemini Files, tải lên có thể tiếp tục (resumable uploads) và cachedContents không có trong bất kỳ cấu hình MCP nào.
• Không bao giờ dán API key vào prompt hoặc đối số của công cụ.

Server TokenLab MCP cung cấp những gì cho một coding agent

Theo tài liệu về MCP server (ghi nhận ngày 03/10/2026), TokenLab MCP Server cho phép client duyệt qua các mô hình và giá cả hiện tại, gửi yêu cầu mô hình, tạo nội dung đa phương tiện, làm việc với tệp và kiểm tra các tác vụ bất đồng bộ. Tài liệu liệt kê các khả năng sau:

• liệt kê các mô hình và đọc khả năng của một mô hình cụ thể (list_models, get_model)
• đọc giá hiện tại hoặc so sánh nhiều mô hình
• gửi Chat Completions, Responses, Anthropic Messages hoặc các yêu cầu Gemini
• đánh giá các quyết định đã được định kiểu với evaluate_decisions
• tạo hoặc chỉnh sửa hình ảnh; tạo video, âm nhạc, 3D, giọng nói, chuyển đổi văn bản thành giọng nói hoặc dịch thuật
• tải lên và truy xuất tệp thông qua API /v1/files tương thích với OpenAI
• tạo embeddings hoặc xếp hạng lại (rerank) tài liệu
• kiểm tra và hủy các tác vụ bất đồng bộ được hỗ trợ (get_task_status để polling)

Tài liệu không liệt kê tên công cụ cho phần giá cả hoặc tổng quan API trong phiên bản này. Bản nháp cũ của chúng tôi từng đặt tên là get_model_pricing và get_api_overview. Hãy kiểm tra danh sách công cụ của client mà bạn đang kết nối trước khi dựa vào hai cái tên đó.

Khả năng sử dụng công cụ phụ thuộc vào cấu hình (profile):

Cấu hình	API key	Bao gồm
catalog	Không yêu cầu	Danh sách mô hình, chi tiết mô hình, giá cả, so sánh, tổng quan API
core	Yêu cầu cho các cuộc gọi trả phí	Các công cụ phổ biến về chat, quyết định, đa phương tiện, âm thanh, tệp, tác vụ, embedding, rerank và dịch thuật
full	Yêu cầu cho các cuộc gọi trả phí	core cộng với các API dành cho nhà phát triển bổ sung

Hãy bắt đầu với catalog nếu bạn chỉ muốn chọn mô hình tốt hơn. Sử dụng core khi client cần tạo nội dung hoặc gọi một mô hình.

Cài đặt TokenLab MCP server trong client của bạn

Gói này yêu cầu Node.js 18.17 trở lên và npx. Nó chạy cục bộ qua stdio, vì vậy bạn không cần cài đặt toàn cục. Hãy sao lưu cấu hình hiện tại của bạn trước và chỉ thêm mục TokenLab. Các lệnh này được lấy từ tài liệu, ghi nhận ngày 03/10/2026.

Claude Code:

claude mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  --scope user \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Codex:

codex mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.26

Cursor (~/.cursor/mcp.json hoặc .cursor/mcp.json):

{
  "mcpServers": {
    "tokenlab": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server@0.6.26"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

VS Code sử dụng .vscode/mcp.json với khóa servers và "type": "stdio". Claude Desktop sử dụng cùng định dạng với Cursor trong claude_desktop_config.json. Sao chép cả hai từ trang tài liệu.

Để kích hoạt các công cụ trả phí, hãy tạo một key trong Console → API keys và thiết lập cả hai biến trong môi trường server:

{
  "env": {
    "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
    "TOKENLAB_MCP_TOOL_PROFILE": "core"
  }
}

Sau đó khởi động lại client và chạy claude mcp list hoặc codex mcp list. Yêu cầu agent gọi list_models. Một danh sách không trống xác nhận rằng gói đã khởi động và kết nối được với TokenLab. Nếu một key thực bị lọt vào tệp chia sẻ, nhật ký hoặc lịch sử shell, hãy thu hồi nó và tạo một key mới.

Quy trình làm việc của một agent: khám phá, kiểm tra, gọi

Đây là quy trình chúng tôi sử dụng. Hãy tưởng tượng một agent được yêu cầu thêm tính năng tạo hình ảnh vào một ứng dụng Node.js. Mọi giá trị dưới đây đều đến từ tài liệu và các trang mô hình trực tiếp được ghi nhận vào ngày 03/10/2026.

1. Khám phá. Yêu cầu danh sách rút gọn hiện tại, bằng công cụ MCP hoặc HTTP thông thường:

{ "tool": "list_models", "arguments": { "recommended_for": "image" } }

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

Các giá trị recommended_for hợp lệ là image, video, music, 3d, tts, stt, embedding, rerank và translation. Giả sử agent chọn nano-banana-pro.

2. Kiểm tra định dạng và giá cả. Gọi get_model, hoặc GET /v1/models/nano-banana-pro (API mô hình trực tiếp, ghi nhận ngày 03/10/2026). Nó báo cáo:

• định dạng yêu cầu được chấp nhận: gemini_generate_content, ánh xạ tới /v1beta/models/{model}:generateContent
• khả năng: image-edit, image-to-image, text-to-image
• giá: per_request là 0.067 USD, với phạm vi giá từ 0.067 đến 0.12 (giá cập nhật ngày 02/10/2026 lúc 16:53:30.068Z)

Một agent giả định sử dụng Chat Completions sẽ viết sai mã. Hãy so sánh với gpt-image-2 (API mô hình trực tiếp). Nó không liệt kê định dạng yêu cầu được chấp nhận và có giá theo token là 3.5 USD đầu vào và 21 USD đầu ra cho mỗi 1 triệu token. Hình thức giá khác nhau tùy theo mô hình, vì vậy agent phải đọc nó cho từng mô hình.

3. Thực hiện cuộc gọi. Đối với một mô hình chat, việc kiểm tra định dạng sẽ quyết định endpoint. gpt-5.6-terra chấp nhận openai_chat_completions và openai_responses (API mô hình trực tiếp, ghi nhận ngày 03/10/2026), vì vậy SDK tiêu chuẩn hoạt động:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)

Gửi ID mô hình đã chọn một cách rõ ràng. Tài liệu nêu rõ rằng TokenLab không tự ý thay thế nó. Client nên yêu cầu phê duyệt trước khi thực hiện cuộc gọi trả phí nếu giá hoặc lựa chọn mô hình chưa được xác nhận.

Để ước tính chi phí, gpt-5.6-terra tính phí 0.6 USD cho mỗi 1 triệu token đầu vào lên đến 272K token đầu vào. Một prompt 10.000 token sẽ có giá khoảng 10.000 / 1.000.000 × 0.6 = 0.006 USD cho đầu vào (ước tính, trước khi tính đầu ra). Trên 272K token đầu vào, toàn bộ yêu cầu sẽ chuyển sang mức giá cao hơn là 1.2 USD đầu vào và 5.4 USD đầu ra.

Các trường API mô hình mà agent nên tin tưởng để định tuyến

Đọc các trường này từ GET /v1/models/{model} (Lấy thông tin mô hình, ghi nhận ngày 03/10/2026):

Trường	Ý nghĩa đối với định tuyến
tokenlab.accepted_request_formats	Họ endpoint cần sử dụng: openai_chat_completions là /v1/chat/completions, openai_responses là /v1/responses, anthropic_messages là /v1/messages
tokenlab.pricing / pricing_unit	Giá công khai hiện tại và đơn vị thanh toán, ví dụ per_token hoặc per_image
tokenlab.max_input_tokens, max_output_tokens	Giới hạn ngữ cảnh và đầu ra. Đối với gpt-5.6-terra: 1.050.000 và 128.000
tokenlab.supported_operations	Các thao tác như chuyển đổi văn bản thành hình ảnh hoặc hình ảnh thành video
tokenlab.lifecycle	Tính khả dụng, ngày phát hành, ngày ngừng hỗ trợ, mô hình thay thế
tokenlab.deliveryAvailability	Hỗ trợ verified và official đã cấu hình. Trường bị thiếu nghĩa là không xác định

Có hai lưu ý. Thứ nhất, định dạng được chấp nhận xác nhận endpoint, nhưng các công cụ và trường riêng lẻ vẫn có thể thay đổi theo mô hình. Thứ hai, deliveryAvailability là hỗ trợ đã cấu hình, không phải là đảm bảo theo thời gian thực. Hãy coi kết quả recommended_for là danh sách rút gọn, vì tài liệu khuyên không nên cố định thứ tự của chúng.

Đối với riêng giá cả, GET /v1/models/{model}/pricing là endpoint chỉ dành cho giá. Các mục phức tạp có thể có các cấp bậc (tiers). Ví dụ, seedance-2.0 có giá đầu ra phụ thuộc vào độ phân giải và đầu vào video từ 2.04 đến 6.545 USD cho mỗi 1 triệu token (API mô hình trực tiếp, ghi nhận ngày 03/10/2026).

Các trường lỗi hướng dẫn phục hồi

Đối với các lỗi Chat Completions và Responses tương thích với OpenAI, hướng dẫn lỗi (ghi nhận ngày 03/10/2026) liệt kê các trường tùy chọn did_you_mean, suggestions, hint, retryable và retry_after. Hãy xử lý mã trạng thái HTTP và code trước. Lỗi 400 model_not_found có thể mang theo did_you_mean. Hãy hiển thị nó cho người dùng thay vì tự ý đổi mô hình. Lỗi 503 all_channels_failed có thể có retryable: false, và việc lặp lại yêu cầu sẽ không giúp ích gì. Anthropic Messages và Gemini giữ nguyên định dạng lỗi gốc của chúng.

Những gì MCP server không thực hiện

Tài liệu nêu rõ các giới hạn sau:

• Nó không thay đổi nhà cung cấp mô hình chính của client. Hãy sử dụng hướng dẫn thiết lập của chính client đó.
• Nó không bao gồm Gemini Files, tải lên có thể tiếp tục hoặc cachedContents. Những tính năng đó cần các cuộc gọi HTTP, theo Gemini Files và cache.
• Nó không phải là Skill. TokenLab Skill cài đặt các hướng dẫn bằng npx skills add và không khởi động MCP server.
• Nó không thực hiện polling cho bạn khi hết thời gian chờ. Nếu kiểm tra trạng thái bị timeout, đừng tạo tác vụ thứ hai.
• Nó không tự làm cho các quyết định trở nên đáng tin cậy. Một câu trả lời Noul từ evaluate_decisions là một xác suất, không phải là Boolean. Hãy xác thực dựa trên các trường hợp được gắn nhãn của riêng bạn.

Cấu hình catalog không thể thực hiện các cuộc gọi trả phí. Các công cụ hình ảnh trả về kết quả hoặc tác vụ, tùy thuộc vào mô hình. Video, âm nhạc và 3D luôn trả về tác vụ.

Nơi bạn vẫn cần các giao diện HTTP thông thường

Trong quy trình của mình, chúng tôi giữ các endpoint khám phá HTTP cùng với MCP cho các agent không dùng MCP. https://api.tokenlab.sh/llms.txt là một bản tổng quan gọn nhẹ với yêu cầu đầu tiên, các endpoint phổ biến và hướng dẫn lỗi. Tài liệu ghi nhận ngày 03/10/2026 không bao gồm tệp llms-full.txt hoặc các tệp snapshot model-data từ bản nháp trước đó của chúng tôi. Hãy tự xác minh các URL đó trước khi phụ thuộc vào chúng. Để biết trạng thái và chi phí trực tiếp, hãy xem Danh mục mô hình công khai.

Câu hỏi thường gặp

Tôi có cần API key để sử dụng TokenLab MCP server không?

Không, không cần để duyệt. Cấu hình catalog liệt kê các mô hình, chi tiết, giá cả và so sánh mà không cần key. Các yêu cầu mô hình trả phí hoặc đa phương tiện cần TOKENLAB_API_KEY trong môi trường server, với cấu hình core hoặc full.

Tôi nên bắt đầu với cấu hình MCP nào?

Bắt đầu với catalog nếu bạn chỉ muốn chọn mô hình tốt hơn. Chuyển sang core khi client cần gọi mô hình hoặc tạo nội dung đa phương tiện. Chỉ sử dụng full nếu agent thực sự cần các API dành cho nhà phát triển bổ sung.

Agent nên tin tưởng vào các trường mô hình nào khi chọn mô hình?

Hãy tin tưởng accepted_request_formats cho endpoint, pricing cùng với đơn vị tính cho chi phí, các giới hạn token, supported_operations và lifecycle. Hãy coi deliveryAvailability là hỗ trợ đã cấu hình, không phải là tính khả dụng trực tiếp.

Tại sao agent của tôi nhận được lỗi 503 all_channels_failed?

Thao tác đó có thể không có nguồn cung trong cấp độ Delivery đã chọn. Khi retryable là false, đừng lặp lại yêu cầu. Kiểm tra tính khả dụng với GET /v1/models và chọn một mô hình khác với sự phê duyệt của người dùng.

MCP server có hỗ trợ Gemini Files hoặc cachedContents không?

Không. Tài liệu cho biết Gemini Files, tải lên có thể tiếp tục và cachedContents hiện yêu cầu các cuộc gọi HTTP. Các công cụ tệp của MCP sử dụng API /v1/files tương thích với OpenAI.

Tạo một key trong Console → API keys, sau đó thêm cấu hình catalog vào client của bạn bằng các lệnh trên.