Drive Vidtsx from Claude.

Overview

MCP (Model Context Protocol) lets AI assistants like Claude call your own server-side tools. The VidTSX MCP exposes three credit-bearing capabilities — image generation, video generation, and speech-to-text — plus a free whoami diagnostic. Every call is billed against your VidTSX credit balance and recorded in your Usage log.

The credit-bearing tools are asynchronous: submit returns a job_id immediately, and you poll the matching get_*_job tool until the job is completed or failed. Credits are reserved at submit and refunded automatically on any failure.

1. Generate an MCP token

Claude.ai's connector UI accepts only a URL — it can't send custom HTTP headers — so the credential has to live in the URL itself. To keep your main license key out of URLs, browser histories, and access logs, the keyed route uses a separate MCP token bound to your license. Each token can be revoked independently; revoking one never affects your license key or the desktop app.

Generate one from the License tab (log in first) — click Generate MCP token and copy the URL once. The format is:

https://learnwithhasan.com/vidtsx/mcp/key/mcpt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/

2. Connect from Claude.ai

1. Open Claude.ai → Settings → Connectors.
2. Click Add custom connector.
3. Name: VidTSX MCP (or anything you like).
4. Paste the URL from step 1.
5. Leave the OAuth fields empty — auth is handled by the URL.
6. Save, then enable the connector for your conversation.

3. Connect with Bearer token (Desktop / Code)

Clients that can send custom HTTP headers should use the canonical, header-authenticated URL — your license key stays out of the URL bar and access logs.

URL:    https://learnwithhasan.com/vidtsx/mcp/
Header: Authorization: Bearer VTSX-XXXX-XXXX-XXXX

For Claude Code, add the connector via the slash command or your MCP config file.

4. Test the connection

Once connected, ask Claude:

Use the VidTSX MCP whoami tool.

Expected output:

# Vidtsx MCP — whoami

- **Email:** [email protected]
- **License key:** `VTSX-XXXX-XXXX-XXXX`
- **Tier:** free
- **Credits available:** 0
- **Connection:** ok

If you get this card, your auth chain is working end-to-end.

5. Diagnostics

If something looks off, hit the status endpoint directly — it always returns 200 so it's safe to probe from a browser or script:

GET https://learnwithhasan.com/vidtsx/mcp/key/mcpt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/status/

{
  "mcp_online": true,
  "authenticated": true,
  "user": {"email": "[email protected]", "tier": "free"},
  "credits_available": 0,
  "license_key": "VTSX-XXXX-XXXX-XXXX"
}

• mcp_online: false → the MCP server is down.
• authenticated: false → your MCP token was revoked or never existed. Generate a new one from the License tab.
• Otherwise it's a Claude.ai connector cache — disconnect and re-add the connector.

How the credit-bearing tools work

Every credit-bearing tool — image, video, transcription — is async: the submit tool reserves credits, queues a background job, and returns a job_id immediately. You then poll the matching get_*_job(job_id) tool until status is completed (read the result) or failed (read error and error_type).

Credits are reserved at submit and refunded on failure. If a job errors for any reason — safety block, timeout, audio too long, anything — your balance is restored. You never net-pay for a job that didn't produce a result.

Submit response shape (the same for all three tools):

{
  "success": true,
  "job_id": "00000000-0000-0000-0000-000000000000",
  "status": "pending",
  "request_id": "..."
}

While in flight you'll see:

{ "success": true, "job_id": "...", "status": "pending" }  // or "running"

Completed and failed shapes are per-tool — see each tool's section below.

Tool: whoami

Tool: generate_image

{
  "success": true,
  "job_id": "...",
  "status": "completed",
  "image_url": "https://s3.powerkit.dev/learnwithhasan-files/vidtsx/generated/abc.png",
  "model_used": "vidtsx-image-01",
  "aspect_ratio": "3:2",
  "credits_consumed": 4,
  "elapsed_seconds": 4.8
}

Tool: generate_video

{
  "success": true,
  "job_id": "...",
  "status": "completed",
  "video_url": "https://s3.powerkit.dev/learnwithhasan-files/vidtsx/videos/abc.mp4",
  "model_used": "vidtsx-video-lite",
  "aspect_ratio": "16:9",
  "duration_seconds": 5,
  "has_audio": false,
  "credits_consumed": 70,
  "elapsed_seconds": 48.2
}

Tool: vidtsx_transcribe

{
  "success": true,
  "job_id": "...",
  "status": "completed",
  "model_used": "vidtsx-stt-smart",
  "text": "Hello world.",
  "words": [
    {"text": "Hello",  "start": 0.12, "end": 0.45, "confidence": 0.99, "speaker": "A"},
    {"text": "world.", "start": 0.50, "end": 0.90, "confidence": 0.97, "speaker": "A"}
  ],
  "utterances": [
    {"speaker": "A", "text": "Hello world.", "start": 0.12, "end": 0.90}
  ],
  "highlights": [{"text": "Hello world", "rank": 0.91, "count": 1}],
  "detected_language": "en",
  "duration_seconds": 60,
  "audio_storage_url": "https://s3.powerkit.dev/learnwithhasan-files/vidtsx/audio/abc.mp3",
  "srt_url": "https://s3.powerkit.dev/learnwithhasan-files/vidtsx/transcripts/abc.srt",
  "credits_consumed": 2,
  "elapsed_seconds": 8.4
}

Status polling

Each submit tool has a free polling companion:

• get_image_job(job_id) — status for a generate_image job.
• get_video_job(job_id) — status for a generate_video job.
• get_transcription_job(job_id) — status for a vidtsx_transcribe job.

All three are free, scoped to the calling user (another user's job returns not_found), and return the same envelope:

• While in flight: {success: true, status: "pending" or "running"}.
• On completed: tool-specific payload (see each tool above).
• On failed: {success: false, status: "failed", error, error_type}.

Error types

The error_type field on a failed job is a stable enum — branch on it instead of parsing error messages:

On any failed job, the credits reserved at submit are refunded automatically. Check the Usage tab to see your MCP activity, credit consumption, and refunds in one place.