Media Upload Guide for MCP

Overview

This document outlines the process of uploading media assets (e.g., images, videos) to NFT collections using MCP (Model Context Protocol) tools and APIs. The process involves authenticating a user, uploading media files to a storage service, and attaching them to an NFT collection. The media is then used to update the collection's metadata, including generating a contract URI for blockchain integration.

📋 Prerequisites: Ensure MCP integration is set up with your API key and user authentication is configured.

Process Flow

flowchart TD
    A[Start: User Authentication] --> B[1. Validate Collection Ownership]
    B --> C[2. Upload Media Files]
    C --> G[3. Update Collection Media]
    G --> H[4. Generate Contract URI]
    H --> I[End: Media Attached]

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style G fill:#f3e5f5

MCP Tools

Upload Collection Media

Tool: add-collection-media

Description: Uploads media files and attaches them to an NFT collection by ID. Validates user ownership and ensures the total media count does not exceed the maximum allowed (2 files).

Input data:

{
  id: string,                      // Collection ID
  files: Array<{                   // Media files to upload (max 2)
    base64: string,                // Base64-encoded media (e.g., "data:image/png;base64,...")
    filename?: string              // Optional filename
  }>
}

📝 File Order: The order of files matters:

• First file — NFT image (used for individual NFT display)
• Second file — Collection cover image (used for collection display)

Output data:

Array<{
  id: string; // Media asset ID
  url: string; // Media URL
  mime: string; // MIME type (e.g., "image/png")
  size: number; // File size in bytes
  w: number; // Width (for images)
  h: number; // Height (for images)
  lg: string | null; // Large thumbnail URL
  md: string | null; // Medium thumbnail URL
  sm: string | null; // Small thumbnail URL
  xs: string | null; // Extra-small thumbnail URL
  blurhash: string; // Blurhash for image preview
}>;

API Endpoint

POST /media/:id/collection

Summary: Upload media and attach them to an NFT collection by ID.

Description: Uploads up to 2 media files (max 10MB each, supported MIME types: image/jpeg, image/png, image/webp, video/mp4, video/webm) and attaches them to the specified collection. Requires user authentication and ownership of the collection.

📝 File Order: The order of files matters:

• First file — NFT image (used for individual NFT display)
• Second file — Collection cover image (used for collection display)

Request:

• Path Parameters:

  {
    id: string; // Collection ID
  }
  

• Form Data:

  {
    files: File[]                  // Media files (max 2, 10MB each)
  }
  

Responses:

• 200 Success:

  Array<{
    id: string;
    url: string;
    mime: string;
    size: number;
    w: number;
    h: number;
    lg: string | null;
    md: string | null;
    sm: string | null;
    xs: string | null;
    blurhash: string;
  }>;
  

• 400 Bad Request: If the total media count exceeds 2 or files are invalid.
• 403 Forbidden: If the user is not the collection owner.

Usage

Upload Media via MCP Tool

const result = await mcp.callTool("add-collection-media", {
  id: "collection-id-123",
  files: [
    {
      base64: "data:image/png;base64,iVBORw0KGgo...",
      filename: "nft-image.png",
    }, // First: NFT image
    { base64: "data:image/png;base64,iVBORw0KGgo...", filename: "cover.png" }, // Second: Collection cover
  ],
});
const media = result.content[0].text; // Array of MediaAsset
console.log("Uploaded Media:", media);

Upload Media via HTTP API

const formData = new FormData();
formData.append("files", nftImageFile); // First: NFT image (e.g., from <input type="file">)
formData.append("files", coverImageFile); // Second: Collection cover

const response = await fetch("/media/collection-id-123/collection", {
  method: "POST",
  headers: { "x-api-key": "your-token" },
  body: formData,
});
const media = await response.json();
console.log("Uploaded Media:", media);

Errors

• Maximum Files Exceeded: "Cannot upload X files. Maximum allowed is 2 files total. Current count: Y"
• Forbidden: "Forbidden" (if the user is not the collection owner)
• Invalid Files: Thrown if files exceed 10MB or have unsupported MIME types.