VidHex MCP Development Document

Connect AI video super-resolution directly into your preferred MCP client—Claude Code, Cursor, VS Code, Windsurf, Claude Desktop, and more. With the MCP (Model Context Protocol), you can upscale videos using simple natural language—no coding required, without ever leaving your editor.

Product Overview & Capabilities

Just say "Upscale this video to 1080p" during conversation, and your AI agent will automatically invoke MCP tools, schedule a processing job, wait for completion, and return the finished download URL. Capabilities available in the current release:

Async vs Sync

Quickstart

1. Get an API Key: Log in to the vidhex member center and generate an API key in the "API Keys" section (formatted like vsk_live_xxxxxxxx).
2. Install and Register (Requires local Python ≥ 3.10):

   pip install vidhex_mcp
   vidhex_mcp install --api-url https://api.example.com --api-key vsk_live_xxxxxxxx

   install registers the MCP server and deploys the skill. When using clients like Cursor or VS Code, manually configure them following the Configuration Table below, or provide the Natural Language Installation prompt directly to your AI client.
3. Restart & Log In: Restart your client, then run vidhex_mcp login in your terminal to complete browser authorization (billing identity).
4. Try a Prompt: Ask your AI: "Upscale demo.mp4 on my desktop to 4K."

Installation & Login

Method 1: Natural Language Installation (Recommended)

If your AI client supports executing commands, simply send the following prompt. The assistant will perform installation, registration, and prompt for restart and login:

Please install Video Skill MCP for me by running the following steps in order:
1. pip install vidhex_mcp
2. vidhex_mcp install --api-url https://api.example.com --api-key vsk_live_xxxxxxxx
3. Once completed, remind me to restart the current AI client (Claude Code / Cursor / VS Code, etc.). After restarting, execute `vidhex_mcp login` to complete browser authorization, and verify the installation using `vidhex_mcp --version`.

Method 2: Manual Installation

pip install vidhex_mcp
vidhex_mcp install --api-url https://api.example.com --api-key vsk_live_xxxxxxxx
vidhex_mcp login        # Run after restarting client to link billing identity via browser

• install: Registers MCP (defaults to Claude Code, use --scope project for project level) + deploys skills + saves credentials + runs startup self-check;
• login: Binds billing identity independently from API Key authentication; run vidhex_mcp status and points to inspect login status and credit balance.

Manual Configuration for Other Clients

{
  "mcpServers": {
    "vidhex_mcp": {
      "command": "vidhex_mcp",
      "env": {
        "VIDEO_SKILL_API_URL": "https://api.example.com",
        "VIDEO_SKILL_API_KEY": "vsk_live_xxxxxxxx"
      }
    }
  }
}

VS Code uses servers at the root level and requires "type": "stdio". Zed uses context_servers with "command": {"path": "vidhex_mcp", "env": {...}}. If the process fails to start, replace the command with its absolute local path.

Verifying Installation

• Run /mcp in Claude Code (or inspect Cursor's Settings → MCP, or VS Code's MCP panel) to verify vidhex_mcp is connected;
• Or ask your AI: "What tools do you currently have available?" — you should see video upscaling and job query tools;
• Run vidhex_mcp --version and vidhex_mcp status in terminal to verify CLI availability and login state.

Points & Consumption

Processing videos consumes points. Accounts hold two categories of points. Deductions consume free quota first, then purchased points:

For standard video: ~1 second of video consumes roughly 1 point. The AI provides an estimated cost before job submission.

Check Balance: Run vidhex_mcp points or check the dashboard; Recharge: Top up on the store checkout page.

Billing & Refunds

• When submitting a job, the estimated points are first held (frozen) and only deducted upon job success. Failed or timed-out jobs are refunded in full; no points are lost.
• If your balance is insufficient, the job is rejected immediately; no partial deductions occur.
• Each API Key has daily/monthly call limits that reset periodically. Contact support to request quota increases.
• If a submission is rejected: Rate limit reached → wait for reset or request a tier upgrade; Insufficient points → run vidhex_mcp points, top up and retry (no job was created, no points deducted).

The current release exposes two tools: Video Super-Resolution and Job Status Query. You do not need to memorize parameters—just instruct your AI in natural language. This reference is for developers verifying schemas and boundaries.

Conventions

Videos must be referenced via local absolute paths (input_path). The MCP server reads and uploads them (large files use direct-to-cloud client uploads). The single file size limit is 2 GiB by default, validated locally prior to upload.

Video Super-Resolution

{
  "input_path": "C:\\Users\\xxx\\demo.mp4",
  "scale": 4,
  "wait": false
}

Job submitted: `job_a1b2c3d4`
Status: processing
Use `check_job_status` with job_id=`job_a1b2c3d4` to check progress.

Jobs & Status

check_job_status

Query the status of submitted jobs; includes output URL and file size when completed. Setting wait=true will poll until finished.

Natural Language Prompts

Once set up, simply speak to your AI agent using everyday language:

• "Help me upscale this video to 1080p: C:\Users\xxx\demo.mp4"
• "Upscale this video 4x: C:\Users\xxx\clip.mp4"
• "Check how many credits I have left in my account"

Error Codes

All error responses comply with the RFC 7807 specification, containing code and message:

FAQs

Execution & Jobs

AI hangs or times out during tool invocation?

MCP clients enforce a ~60-second execution timeout per tool call, whereas video jobs typically run longer. Always favor asynchronous mode (wait=false to receive a job_id, followed by polling via check_job_status). If you must use sync mode, make sure to configure a sufficiently high timeout (default: 600s).

What are the input file requirements?

• Use local absolute paths. Dragging and dropping files into chat often drops path information; ensure you explicitly supply the full system path;
• Videos support mp4, mov, avi, mkv, webm containers; images support png, jpg, webp;
• Default file size limit is 2 GiB. Please trim or compress files before submitting if they exceed this limit.

Job status is marked as failed. How to debug?

Use check_job_status to read the error.message field. Common causes include: corrupted/unplayable media, or unsupported parameter combinations (such as invalid scale multipliers). Verify and retry or contact support.

Installation & Setup

Getting "Configuration error" or "API key is not set"?

Your MCP configuration is incomplete: verify that the environment variables contain VIDEO_SKILL_API_URL (not a placeholder URL) and VIDEO_SKILL_API_KEY, or re-run vidhex_mcp install --api-url … --api-key …. See Auth & Config.

"Command not found", or MCP Server shows red status in client?

• Command not found: Run pip install vidhex_mcp and verify with which vidhex_mcp that it is on your system PATH; ensure your IDE/terminal shares the same Python virtual environment;
• Server highlighted in red: Verify the client process successfully spawned the server (Claude Code: /mcp, Cursor: Settings → MCP, VS Code: MCP panel). Common triggers: missing environment variables, invalid API key, or command not found in PATH (specify absolute path in config).

Billing & Points

Points deducted before completion? Quota or points insufficient?

• Points shown as deducted upon submission are merely frozen (on hold): they are permanently charged only if the task succeeds, and refunded in full if it fails. See Billing & Refunds;
• Quota exhausted (429): Wait for daily/monthly reset, or contact support for higher limits;
• Insufficient points (402): Run vidhex_mcp points to view balance, top up via store, and retry—no task was created and no points were deducted;
• Console shows "Balance temporarily unavailable": Balance is queried in real time; an expired session may cause this. Re-login on the vidhex portal to restore status.