Mage

npx add-mcp 'https://mcp.mage.space/mcp'

Dùng Mage từ Claude, ChatGPT, Grok và Cursor

Kết nối Claude, ChatGPT, Claude Code, Grok hoặc Cursor với tài khoản Mage của bạn thông qua máy chủ Mage MCP, sau đó yêu cầu trợ lý tạo hình ảnh, video và âm thanh, thanh toán bằng Gems.

Máy chủ Mage MCP kết nối các trợ lý AI với tài khoản Mage của bạn. Sau khi kết nối, bạn có thể yêu cầu Claude, ChatGPT, Claude Code, Grok hoặc Cursor chọn một mô hình, báo giá, tạo hình ảnh, video hoặc đoạn âm thanh, và mang kết quả về. Nó cũng đọc lịch sử tạo của bạn và các sáng tạo đã lưu, đồng thời sử dụng các nhân vật và tham chiếu đã lưu của bạn.

https://mcp.mage.space/mcp

[!WARNING]

Mọi lần tạo mà trợ lý của bạn khởi chạy đều được thanh toán bằng Gems từ tài khoản của bạn. Trợ lý của bạn có thể kiểm tra giá trước, và bạn có thể ngắt kết nối bất cứ lúc nào.

Kết nối trợ lý của bạn

Claude

Hoạt động trong Claude trên web, ứng dụng máy tính để bàn, ứng dụng di động và Cowork.

1. Mở Kết nối Mage với Claude. Tên trình kết nối và URL đã được điền sẵn. Chọn Add.
2. Chọn Connect. Một trang Mage mở ra và yêu cầu bạn đăng nhập nếu chưa đăng nhập.
3. Kiểm tra rằng trang hiển thị tên ứng dụng bạn đang kết nối, sau đó chọn Connect. Bạn quay lại Claude.
4. Trong một cuộc trò chuyện, bật trình kết nối Mage từ menu + dưới Connectors, và yêu cầu những gì bạn muốn tạo.

Trên gói Team hoặc Enterprise, chủ sở hữu trước tiên thêm trình kết nối trong Organization settings → Connectors. Gói Free cho phép một trình kết nối tùy chỉnh.

ChatGPT

Thêm Mage như một plugin cá nhân từ trang Plugins của ChatGPT.

1. Mở ChatGPT Plugins.
2. Nhấp Add, sau đó chọn Create MCP App.
3. Nhập Mage cho Name, https://mcp.mage.space/mcp cho Server URL, và chọn OAuth cho Authentication. Để trống Advanced OAuth settings; không cần client ID hay client secret. Biểu tượng và mô tả là tùy chọn.
4. Xem lại thông báo, đánh dấu I understand and want to continue, sau đó nhấp Create.
5. Đăng nhập vào Mage trên trang mở ra, kiểm tra tên ứng dụng, và chọn Connect.
6. Cài đặt Mage từ plugin Personal của bạn, bắt đầu một cuộc trò chuyện Work, và nhắc đến @Mage.

[!NOTE]

Nếu thiếu Create MCP App, hãy bật Developer mode trong Settings → Security and login của ChatGPT, sau đó quay lại Plugins. Xem hướng dẫn thiết lập của ChatGPT để biết thêm chi tiết.

Claude Code

Thêm máy chủ, sau đó đăng nhập từ Claude Code:

claude mcp add --transport http mage https://mcp.mage.space/mcp

Chạy /mcp trong Claude Code, chọn mage, và xác thực. Một trang trình duyệt mở ra để bạn đăng nhập vào Mage và chọn Connect.

Để dùng API key thay vì đăng nhập:

claude mcp add --transport http mage https://mcp.mage.space/mcp \
  --header "Authorization: Bearer $MAGE_API_KEY"

Grok

Thêm Mage như một trình kết nối MCP tùy chỉnh.

1. Mở Grok connectors, chọn New Connector, sau đó chọn Custom.
2. Nhập https://mcp.mage.space/mcp và hoàn tất các bước xác thực để kết nối tài khoản Mage của bạn.
3. Bắt đầu một cuộc trò chuyện và yêu cầu Grok dùng Mage để tạo hình ảnh, video hoặc âm thanh.

Trên Grok Business hoặc Enterprise, quản trị viên nhóm trước tiên phải cấp phát trình kết nối trong cloud console.

Cursor

Nút này cài đặt Mage với client ID OAuth công khai của nó; đăng nhập vào Mage khi được nhắc. Nếu Mage đã được cài đặt, hãy thay thế cấu hình hiện có bằng cấu hình từ liên kết này. Nếu nút không làm gì, hãy mở liên kết cài đặt web thay thế: nó mở Cursor từ trình duyệt và hiển thị cùng cấu hình để thêm thủ công.

Để thiết lập thủ công, thêm mục này vào ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mage": {
      "url": "https://mcp.mage.space/mcp",
      "auth": {
        "CLIENT_ID": "https://cursor.com/mcp",
        "scopes": [
          "mage",
          "offline_access"
        ]
      }
    }
  }
}

Client ID là công khai và không cần client secret. Cursor sử dụng cấu hình OAuth tĩnh để mở trang đồng ý của Mage.

Bạn cũng có thể kết nối bằng API key:

{
  "mcpServers": {
    "mage": {
      "url": "https://mcp.mage.space/mcp",
      "headers": { "Authorization": "Bearer ${env:MAGE_API_KEY}" }
    }
  }
}

Khi một ứng dụng kết nối bằng cách đăng nhập, Mage hiển thị ai đang yêu cầu trước khi bất cứ điều gì được chia sẻ: tên ứng dụng, trang web nguồn, và nơi bạn quay lại sau đó. Phiên khách không thể kết nối ứng dụng; hãy đăng nhập bằng tài khoản Mage của bạn trước.

Trợ lý của bạn có thể làm gì

Công cụ	Chức năng
list_models	Liệt kê các mô hình được đề xuất cùng giá, mỗi mô hình phù hợp nhất với việc gì, và các đánh đổi của nó; các mô hình còn lại theo yêu cầu.
get_model	Mô tả một mô hình: các trường, giá trị cho phép, giá trị mặc định, quy tắc và giá.
estimate_cost	Báo giá một lần tạo trước khi bắt đầu. Không tính phí.
create_upload	Lấy liên kết có chữ ký để tải tệp lên từ máy tính của bạn, dành cho các trợ lý có thể chạy lệnh.
generate	Bắt đầu một lần tạo, thanh toán bằng Gems.
get_request	Chờ một lần tạo hoàn tất và trả về liên kết kết quả.
cancel_request	Dừng một lần tạo đang chạy. Gems không được hoàn lại.
get_account	Hiển thị tài khoản đã kết nối và số dư Gems của nó.
list_characters	Liệt kê các nhân vật của bạn và các @handle của chúng.
create_character	Lưu một nhân vật riêng tư từ liên kết hình ảnh, tùy chọn kèm đoạn âm thanh giọng nói.
delete_character	Xóa một trong các nhân vật của bạn.
list_references	Liệt kê trang phục, tư thế, địa điểm, đồ vật và đoạn âm thanh giọng nói của bạn, tất cả hoặc một loại.
create_reference	Lưu một tham chiếu riêng tư từ liên kết hình ảnh hoặc âm thanh.
delete_reference	Xóa một trong các tham chiếu của bạn.
list_history	Liệt kê các lần tạo của bạn trong 30 ngày qua, bao gồm cả những lần bạn tự tạo trong Mage.
search_creations	Tìm kiếm các sáng tạo bạn đã lưu, theo nội dung chúng hiển thị, theo bộ sưu tập hoặc theo ngày.

Nhắc đến một nhân vật hoặc tham chiếu đã lưu trong yêu cầu bằng handle của nó, ví dụ "Make a portrait of @ana wearing @red-coat", và trợ lý của bạn sẽ chuyển nó cho mô hình.

Kỹ năng

Kỹ năng Mage dạy trợ lý của bạn hoàn thành các công việc trọn vẹn dựa trên các công cụ này: chụp ảnh sản phẩm, niêm yết trên sàn thương mại, biến thể quảng cáo, video UGC và video không lộ mặt, hình thu nhỏ YouTube, và các ứng dụng Mage, từ hoán đổi khuôn mặt và thay đổi ánh sáng đến chỉnh sửa video và khớp khẩu hình. Thêm chúng bằng npx skills add mage-space/skills, hoặc xem qua chúng cùng ví dụ tại mage.space/skills.

Trợ lý của bạn dùng mô hình nào

Trừ khi bạn chỉ định một mô hình, trợ lý của bạn tạo hình ảnh bằng Mango 3, video bằng Cherry 2 Pro, và âm thanh bằng Seed Audio. Nó cho bạn biết mô hình và giá trước khi bắt đầu, và sau một kết quả, nó có thể gợi ý một lựa chọn thay thế khi đánh đổi của nó phù hợp với việc bạn đang làm.

	Hình ảnh	Video
Mặc định	Mango 3	Cherry 2 Pro
Cùng dòng	Mango 3S (rẻ hơn, tối đa 3K), Mango 2 (tối đa 4K), Mango	Cherry Pro (4K), Cherry, Cherry Mini (Cherry rẻ nhất)
Cũng được đề xuất	Guava 2 Pro và Guava 2 (chân thực), GPT Image 2.5 Flare (văn bản và chỉnh sửa chính xác)	Lemon (khung đầu và khung cuối, clip tối đa 30 giây)

Mọi mô hình khác chỉ chạy khi bạn yêu cầu theo tên, ví dụ "make it with Melon" hoặc "use Nano Banana 2". Trợ lý của bạn có thể gợi ý một mô hình khi nó phù hợp hơn với yêu cầu, chẳng hạn mô hình anime cho một clip anime, và chờ câu trả lời của bạn. Tôi nên dùng mô hình nào? so sánh tất cả chúng.

Cherry 2 Pro là mô hình video mạnh nhất và đắt nhất của Mage, và giá của nó tăng vọt theo độ phân giải và độ dài. Hãy yêu cầu Cherry Mini hoặc Lemon trong khi bạn đang phác thảo.

Cách các lần tạo hoạt động

1. Trợ lý của bạn chọn một mô hình bằng list_models, như trên, và đọc các trường của nó bằng get_model.
2. Nó kiểm tra giá bằng estimate_cost, công cụ này cũng phát hiện một yêu cầu mà mô hình sẽ từ chối. Giá của video phụ thuộc vào độ dài của nó: Mage đo một video đã có trên Mage, chẳng hạn tệp đã tải lên hoặc kết quả trước đó, khi nó báo giá, và một video được liên kết từ trang khác chỉ khi lần tạo bắt đầu.
3. Nó bắt đầu lần tạo bằng generate, công cụ này tính Gems của bạn. Mỗi lần tạo mang một khóa do trợ lý của bạn tạo ra, nên một lần thử lại sau khi mất kết nối sẽ trả về cùng lần tạo thay vì trả tiền hai lần.
4. Nó chờ bằng get_request cho đến khi kết quả sẵn sàng và đưa bạn liên kết.

Kết quả vẫn khả dụng trong 30 ngày: hãy tải xuống những gì bạn muốn giữ, hoặc lưu nó trong Mage. Một kết quả bị kiểm duyệt gắn cờ NSFW sẽ được đánh dấu như vậy. Xem Requests để biết các trạng thái mà một lần tạo trải qua và Billing để biết cách tính Gems.

Hình ảnh và tệp

Đầu vào đa phương tiện, chẳng hạn khung đầu, hình ảnh tham chiếu hoặc video cần chỉnh sửa, là các liên kết: một liên kết https công khai đến chính tệp đó, hoặc một data URL tối đa khoảng 3 MB.

• Claude Code, Cursor và các trợ lý khác chạy lệnh có thể tải tệp lên từ máy tính của bạn: chúng lấy liên kết tải lên có chữ ký bằng create_upload, gửi tệp đến đó, và dùng liên kết mới của tệp như bất kỳ liên kết nào khác. Một tệp có thể lên đến 100 MB và bị xóa sau 30 ngày. Mỗi lần tải lên chứa một tệp: một tệp đã sửa sẽ được tải lên như một lần tải mới, vì liên kết cũ có thể vẫn hiển thị tệp đầu tiên trong tối đa 4 giờ.
• Các cuộc trò chuyện Claude, ChatGPT và Grok không thể chuyển một tệp bạn đính kèm vào cuộc trò chuyện sang Mage. Hãy chia sẻ liên kết trực tiếp đến tệp thay thế, hoặc dùng một sáng tạo đã có trên Mage.
• Một liên kết đến trang web, chẳng hạn video YouTube hoặc TikTok, không phải là tệp và sẽ bị từ chối.

Quản lý ứng dụng đã kết nối

Mọi ứng dụng bạn đã kết nối được liệt kê trong MCP → Connected apps, cùng thời điểm bạn kết nối và lần sử dụng gần nhất. Chọn Disconnect để dừng một ứng dụng ngay lập tức; nó không thể dùng tài khoản của bạn hoặc tiêu Gems của bạn cho đến khi bạn kết nối lại. Mở MCP trong thanh điều hướng nổi, sau đó chọn Connected apps.

Giới hạn

• Tối đa 20 lần tạo có thể chạy cùng lúc cho tài khoản của bạn, giống như với API.
• Một ứng dụng có thể thực hiện tối đa 120 lệnh gọi công cụ mỗi phút.
• get_request chờ tối đa 2 phút mỗi lần gọi; trợ lý của bạn gọi lại nó cho các lần tạo dài hơn.

Khắc phục sự cố

• Cursor báo "Incompatible auth server: does not support dynamic client registration": cập nhật mục Mage hiện có trong ~/.cursor/mcp.json để bao gồm khối auth từ phần thiết lập Cursor ở trên, sau đó kết nối lại. Chỉ một URL máy chủ không bao gồm client ID Cursor đã đăng ký trước của Mage.

• "Couldn't reach the MCP server": kiểm tra rằng URL chính xác là https://mcp.mage.space/mcp, sau đó xóa trình kết nối và thêm lại.

• Kết nối yêu cầu bạn đăng nhập lại: kết nối kéo dài tối đa 180 ngày, sau đó ứng dụng yêu cầu bạn phê duyệt lại. Ngắt kết nối trong Mage cũng kết thúc nó.

• Một lần tạo thất bại với insufficient_gems: thêm Gems trong API → Billing và thử lại.

Tài liệu này được xây dựng và lưu trữ trên Mintlify, một nền tảng tài liệu dành cho nhà phát triển.