Máy chủ MCP

SeedRouter vận hành một máy chủ Model Context Protocol từ xa. Tác tử AI có thể dùng máy chủ này để liệt kê các mô hình ảnh và video, đọc lược đồ yêu cầu và giá, gửi tác vụ tạo nội dung và lấy kết quả mà bạn không cần viết mã tích hợp.

https://api.seedrouter.ai/v1/mcp

• Giao thức truyền tải: Streamable HTTP, không lưu trạng thái. Máy chủ hỗ trợ phiên bản giao thức 2026-07-28 và các phiên bản trước đó bắt đầu bằng bước bắt tay initialize, ngược về đến 2024-11-05.
• Xác thực: khóa API SeedRouter của bạn dưới dạng token Bearer, Authorization: Bearer YOUR_API_KEY. Tạo khóa trên trang Khóa API; xem Xác thực.
• Tính phí: giống HTTP API. Mỗi lần gọi submit_task là một yêu cầu đến endpoint tác vụ tương ứng và được tính phí theo cùng cách.

Các client chỉ có thể đăng nhập bằng OAuth và không có trường nhập header tùy chỉnh hiện chưa thể kết nối.

Kết nối client

Trang Khóa API có nút Kết nối qua MCP để điền một trong các khóa của bạn vào cấu hình cho từng client bên dưới.

Claude Code

claude mcp add --transport http seedrouter https://api.seedrouter.ai/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

Thêm vào ~/.cursor/mcp.json hoặc .cursor/mcp.json trong một dự án:

{
  "mcpServers": {
    "seedrouter": {
      "url": "https://api.seedrouter.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Codex CLI

Codex đọc khóa từ một biến môi trường:

export SEEDROUTER_API_KEY=YOUR_API_KEY
codex mcp add seedrouter --url https://api.seedrouter.ai/v1/mcp \
  --bearer-token-env-var SEEDROUTER_API_KEY

Codex lưu tên biến, không lưu khóa. Hãy khởi động Codex từ shell đã đặt SEEDROUTER_API_KEY, chẳng hạn bằng cách export biến này trong tệp cấu hình shell.

VS Code

Thêm vào .vscode/mcp.json:

{
  "servers": {
    "seedrouter": {
      "type": "http",
      "url": "https://api.seedrouter.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Bất kỳ client nào khác hỗ trợ máy chủ Streamable HTTP từ xa với header Authorization tùy chỉnh đều được thiết lập theo cách tương tự.

Công cụ

submit_task không có tính lũy đẳng. Gọi lại sẽ tạo tác vụ thứ hai và trừ thêm tiền từ số dư, vì vậy hãy kiểm tra get_task, get_balance hoặc lịch sử tác vụ trước khi thử lại nếu bạn chưa nhận được kết quả của lần gọi trước.

Quy trình thông thường

1. Gọi list_models với endpoint: "images".
2. Gọi get_model_schema cho mô hình bạn đã chọn.
3. Có thể gọi get_pricing để xem trước biểu phí.
4. Gọi submit_task với model và input khớp với lược đồ.
5. Gọi get_task với wait_seconds: 50, lặp lại khi status vẫn là processing, rồi đọc output. Tác vụ Seedance báo queued và running trước khi chuyển sang succeeded.

Quá trình tạo diễn ra bất đồng bộ, giống hệt HTTP API: submit_task trả về ngay khi tác vụ được tiếp nhận. wait_seconds giúp tác tử không phải truy vấn trong vòng lặp, nhưng video dài vẫn có thể cần nhiều lần gọi get_task. Nếu việc kiểm tra trạng thái thất bại vì lý do tạm thời trong lúc chờ, chẳng hạn giới hạn tần suất yêu cầu hoặc lỗi máy chủ, get_task trả về kết quả processing gần nhất thay vì lỗi; hãy gọi lại.

Các quy tắc kế thừa từ HTTP API

• Ảnh, video và âm thanh tham chiếu phải là URL http(s) công khai. Dữ liệu đầu vào dạng Base64 bị từ chối.
• Khi HTTP API phản hồi, phần thân phản hồi được trả nguyên vẹn làm kết quả công cụ, với cùng mã lỗi. Các lỗi phát sinh trước khi yêu cầu đến API, chẳng hạn mô hình không xác định hoặc đối số công cụ không hợp lệ, được trả về dưới dạng thông báo lỗi thuần văn bản. Khóa bị từ chối ngay tại endpoint MCP trả về HTTP 401.
• Tác vụ thất bại không bị tính phí.
• Theo mặc định, một tài khoản có thể có tối đa 50 tác vụ ảnh và video đang chạy đồng thời. Các lần gửi tiếp theo trả về HTTP 429 với mã 30002 cho đến khi các tác vụ đang chạy hoàn tất; xem Sử dụng SeedRouter từ tác tử AI.
• ID mô hình và tham số là những giá trị trong tài liệu của từng mô hình. Mô hình xuất hiện trong list_models khi đã được cung cấp trên API.
• Các mô hình văn bản không được cung cấp qua MCP. Hãy gọi chúng qua endpoint văn bản hoặc chạy tác tử lập trình trên các mô hình đó như mô tả trong Tác tử lập trình trên SeedRouter.