MCP Server

Introduction

MediaLit includes a built-in Model Context Protocol (MCP) server. Instead of forcing external AI coding assistants (like Claude Code, Cursor, or ChatGPT) to interact through raw REST endpoints, they can query the MCP server to directly discover and run high-level tools.

The server uses the Streamable HTTP transport. Unlike standard stdio-based MCP servers that require running a separate subprocess, the MediaLit MCP server is mounted directly inside the main Express application at the /mcp route. This allows it to:

• Run on the same port and share the same SSL certificates.
• Reuse the application's authentication middlewares.
• Be accessible to both remote cloud-based clients (like ChatGPT) and local workspace assistants (like Claude Code).

How to Connect

MediaLit supports two ways to authenticate your MCP client. Using the OAuth 2.0 setup is recommended as it is the easiest and most secure option.

1. OAuth 2.0 Setup (Recommended)

Connecting with OAuth is straightforward:

1. Enter the Connection URL: Provide the client with the MediaLit MCP server URL: https://api.medialit.cloud/mcp
2. Redirect & Login: The client will redirect you to the MediaLit login screen.
3. Authorize: Enter your email address to log in, and authorize the connection.

Once approved, you are logged in and the client will automatically handle connection keys in the background.

2. API Key Setup (Alternative)

If you are using developer-focused tools like Cursor or Claude Code and prefer a quick configuration, you can use your MediaLit account API key instead.

Add the following config to your client:

• Header: x-medialit-apikey
• Value: YOUR_API_KEY

Claude Desktop Configuration (claude_desktop_config.json):

Since Claude Desktop communicates via standard input/output (stdio), you must use a proxy/bridge tool like mcp-remote to connect to the remote Streamable HTTP server:

{
  "mcpServers": {
    "medialit": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.medialit.cloud/mcp",
        "--header",
        "x-medialit-apikey: ${API_KEY}"
      ],
      "env": {
        "API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

VS Code configuration (mcp.json):

{
    "servers": {
        "medialit": {
            "type": "http",
            "url": "https://api.medialit.cloud/mcp",
            "headers": {
                "x-medialit-apikey": "YOUR_API_KEY"
            }
        }
    }
}

Two-Step Upload Flow (Drafts & Sealing)

To prevent cluttering of the media registry with unfinished uploads, MediaLit enforces a two-step upload pattern across both REST and MCP interfaces:

1. Upload (upload_media): The file is written to storage, and a record is created with temp: true. In this temporary state, the file does not appear in paginated listings (list_media), count queries (get_media_count), or storage totals (get_total_storage).
2. Seal (seal_media): The client verifies the upload and seals it. Sealing removes the temp flag, finalizing the record and making it globally visible to listing tools.

Tools Reference

The MediaLit MCP server exposes the following tools to connected agents:

Media Management

list_media

Returns a paginated list of finalized (sealed) media items.

• Inputs:
  • page (number, optional): Page offset (default: 1).
  • limit (number, optional): Items per page (default: 10).
  • access ("public" | "private", optional): Filter by accessibility level.
  • group (string, optional): Filter by custom group label.
• Output: { mediaItems: Array, total: number, page: number }

get_media

Fetches complete metadata for a single media item by its ID.

• Inputs:
  • mediaId (string, required): The unique ID of the media item.
• Output: The media document.
• Note: Unlike list_media, this tool can fetch temp: true (unsealed) media items, allowing validation before sealing.

get_media_count

Returns the total count of finalized media items in the account.

• Output: { count: number }

get_total_storage

Returns the total storage space consumed by the account, along with the allowed maximum limit in bytes.

• Output: { storage: number, maxStorage: number }

seal_media

Finalizes a temporary media upload, allowing it to persist and show up in lists/tallies.

• Inputs:
  • mediaId (string, required): The unique ID of the media item to seal.
• Output: The updated media document.

delete_media

Permanently deletes a media file and all generated derivatives (thumbnails, WebP conversions) from storage.

• Inputs:
  • mediaId (string, required): The unique ID of the media item to delete.
• Output: { deleted: true, mediaId: string }

File Uploading & Access

upload_media

Uploads a new file directly using base64-encoded payload parameters.

• Inputs:
  • fileBase64 (string, required): Base64-encoded string of the file bytes.
  • fileName (string, required): Filename with extension (e.g. image.png).
  • mimeType (string, required): The MIME type of the file (e.g. image/png).
  • caption (string, optional): Text description or caption.
  • access ("public" | "private", optional): Access controls (default: private).
  • group (string, optional): Custom folder/group tag.
• Output: { mediaId: string }
• Limits: Maximum payload size is restricted to 10MB. For larger files, generate a signature and use the TUS protocol via REST.

create_upload_signature

Generates a time-limited HMAC signature to authorize direct browser-to-bucket uploads.

• Inputs:
  • group (string, optional): Optional group to associate with the uploaded file.
• Output: { signature: string }

Media Settings

get_media_settings

Retrieves the active image processing configurations for the account, such as auto-conversion behaviors.

• Output: Active configurations (WebP defaults, thumbnail dimensions).

update_media_settings

Overwrites specific image processing defaults. Supply only the properties you wish to modify.

• Inputs:
  • useWebP (boolean, optional): Auto-convert uploaded images to WebP.
  • webpOutputQuality (number, optional): Output quality between 0 and 100.
  • thumbnailWidth (number, optional): Default width of generated thumbnails.
  • thumbnailHeight (number, optional): Default height of generated thumbnails.
• Output: { updated: true }