@avclabs.ai/media-mcp

Node.js >=18 · MIT License

Release statusnpm latest is 0.2.1 with 3 video tools and 2 SAM3 tools. The repository's 4 image tools are an unreleased 0.3.0 candidate and are not production-ready yet.

Config

Variable Name	Required	Default	Description
API_KEY	Yes	-	API authentication key (shared by video, image, and SAM3 services)
HTTP_API_BASE_URL	No	https://mcp.avc.ai/enhance	Video enhancement service endpoint URL
IMAGE_API_BASE_URL	No	https://mcp.avc.ai/enhance	Unreleased 0.3.0 image endpoint; production must use /image and not the /enhance fallback
SAM3_API_BASE_URL	No	https://mcp.avc.ai/sam	SAM3 service endpoint URL
SAM3_POLL_INTERVAL	No	2000	SAM3 polling interval (milliseconds)
SAM3_POLL_MAX_ATTEMPTS	No	25	SAM3 maximum polling attempts

Custom Service Endpoint

json

{
  "env": {
    "HTTP_API_BASE_URL": "https://your-video-endpoint.com",
    "IMAGE_API_BASE_URL": "https://your-image-endpoint.com",
    "API_KEY": "your-api-key",
    "SAM3_API_BASE_URL": "https://your-sam3-endpoint.com"
  }
}

No installation needed, start the MCP Server directly via npx:

bash

npx -y @avclabs.ai/media-mcp@0.3.0 --base-url https://your-video-endpoint.com --image-base-url https://your-image-endpoint.com --api-key your-api-key --sam3-base-url https://your-sam3-endpoint.com

Recommended Workflow

This project provides both sync and async modes.

Important NoteDue to the ~60 second timeout limit for a single tool call in MCP Agents, time-consuming tasks (video enhancement) strongly recommend using async mode.

Async Mode (Recommended)

Video enhancement:

Call create_task to create a task → immediately get task_id
Wait a few seconds, then call get_task_status to query status
If status is processing, continue waiting and repeat step 2
If status is completed, task is done, result contains video_url
If status is failed, task failed, result contains error_message

Sync Mode (Simple Scenarios)

Video enhancement:

Call enhance_video_sync → server internally auto-polls
Max wait 50 seconds by default
If completed within 50s, returns result directly
If not completed within 50s, returns task_id and prompt, let Agent switch to get_task_status to continue querying

Image segmentation (SAM3):

Call sam3_predict → server internally auto-polls
Max wait 50 seconds by default (25 times × 2s polling interval)
If completed within 50s, returns segmentation result directly
If not completed within 50s, returns truncation prompt indicating task is still processing

File Upload Notes

When type is local, the MCP Server will:

Read local file
Upload directly to TOS object storage via presigned URL
Maximum file size: 100MB