Configuration Reference

@avclabs.ai/media-mcp · Node.js >=18 · MIT License

Release statusnpm latest is 0.3.0 with all 9 tools (3 video + 4 image + 2 SAM3), all production-ready. Standalone per-capability packages (video / image / SAM3 segmentation) are coming soon.

Config

Environment variables are scoped per package — each table lists only the variables that package reads.

Video Enhancement

Package:@avclabs.ai/video-mcp· 3 toolsComing soon

This standalone package is not on npm yet; these tools are available today in the all-in-one package.

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 Enhancement

Package:@avclabs.ai/image-mcp· 4 toolsComing soon

This standalone package is not on npm yet; these tools are available today in the all-in-one package.

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	-	Image service endpoint URL; when unset it falls back to the resolved video base URL from HTTP_API_BASE_URL

Image Segmentation (SAM3)

Package:@avclabs.ai/sam3-mcp· 2 toolsComing soon

This standalone package is not on npm yet; these tools are available today in the all-in-one package.

Variable Name	Required	Default	Description
API_KEY	Yes	-	API authentication key (shared by video, image, and SAM3 services)
SAM3_API_BASE_URL	No	https://mcp.avc.ai/sam	SAM3 service endpoint URL
SAM3_POLL_INTERVAL_MS	No	2000	SAM3 polling interval (milliseconds). The canonical name is SAM3_POLL_INTERVAL_MS; SAM3_POLL_INTERVAL is a deprecated alias that still works
SAM3_POLL_MAX_ATTEMPTS	No	25	SAM3 maximum polling attempts

Legacy all-in-one package

Package:@avclabs.ai/media-mcp· 9 tools

The legacy all-in-one package reads all 6 variables:

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	-	Image service endpoint URL; when unset it falls back to the resolved video base URL from HTTP_API_BASE_URL
SAM3_API_BASE_URL	No	https://mcp.avc.ai/sam	SAM3 service endpoint URL
SAM3_POLL_INTERVAL_MS	No	2000	SAM3 polling interval (milliseconds). The canonical name is SAM3_POLL_INTERVAL_MS; SAM3_POLL_INTERVAL is a deprecated alias that still works
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 -p @avclabs.ai/media-mcp@latest media-mcp --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

CLI flag overrides

Precedence, highest to lowest: CLI > environment variables > in-package config.json > built-in defaults. Available flags: --base-url, --image-base-url, --sam3-base-url, --api-key, --sam3-poll-interval, --sam3-poll-max-attempts.

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 & image sync tools (45s truncation):

Call a sync tool (enhance_video_sync, enhance_image_sync, …) → the server polls internally
Max wait 45 seconds by default
If completed within 45s, returns result directly
If not completed within 45s, returns task_id and prompt, let Agent switch to get_task_status to continue querying

Image segmentation, SAM3 (~50s truncation):

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